Breaking Changes

Where possible, I've tried to avoid breaking changes but there are a few potential pitfalls:

• Theming: Trestle no longer reads theme variables from app/assets/stylesheets/trestle/_theme.scss. Instead define theme colors in config/initializers/trestle.rb:

# Define primary and secondary theme colors. Color values may be specified
# as either 3- or 6-digit hex codes, or rgb/hsl() triplets.
config.theme = { primary: "#338ab7", secondary: "#719dc3" }

• Custom views: If you've customized your views by copying over the templates from the Trestle source, you'll want to merge in the updates from this branch to ensure that the required Turbo frames are present. Hopefully overriding views in this way won't be necessary for much longer as the custom actions API will be one of the next major pieces I'll be working on.

• Bootstrap 5 changes: In particular, Bootstrap 5.x changed a number of class names from -l/-left/-r/-right to -s/-start/-e/-end. e.g. ml-2 becomes ms-2, dropdown-menu-right becomes dropdown-menu-end. If you are using any of these in your code, they will need to be updated. See https://getbootstrap.com/docs/5.0/migration/ and https://getbootstrap.com/docs/5.2/migration/ for further information on changes within Bootstrap.

• UJS: The rails-ujs library has been removed, so some data attributes may need to be updated to the Turbo equivalent. In particular, using method: :post on a link should be replaced with data: { turbo_method: :post }. See more info on Turbo replacements at https://guides.rubyonrails.org/working_with_javascript_in_rails.html#replacements-for-rails-ujs-functionality.

• sassc-rails: If you are using the sassc-rails gem, you may experience compilation failures in production or test environments ("Not enough space" error from Sass). A shim will be added in the next release, but this can alternatively be solved by either removing 'sassc-rails' (if no longer required), adding the sassc-embedded gem alongside, or replacing with dartsass-sprockets.

Deprecations

• Defining a dialog form with form dialog: true has been deprecated. Instead use form modal: true. It is also now possible to specify modal options e.g. form modal: { class: "modal-lg", controller: "stimulus-controller" }

• The dialog_request? helper has been deprecated. Use modal_request? instead.

• Setting Trestle.config.turbolinks is deprecated. Turbo will always be used within Trestle views, and is provided by the Trestle JS bundle.

• Hooking into Trestle JS callbacks using Trestle.ready(function() { and Trestle.init(function(root) is deprecated. They'll continue to work for now but will be removed by the time 1.0 rolls around. Stimulus controllers are a much better option for integrating custom code.