Hotwire Support

[spohlenz]

After keeping this development behind closed doors for way too long, I'm excited to finally publicly release one of the largest Trestle updates yet -- the Trestle Hotwire update. This has been a branch two years in the making, and brings the Trestle front-end much more up-to-date and in-line with modern Rails development practices.

Among the things I'm most excited about with this release are the full Stimulus integration, making it easier to override and extend default behavior; Turbo frames, and an easier pathway to real-time updates with Turbo streams; Sass no longer being a required dependency for theming, making it possible to live alongside applications using Tailwind CSS; as well as run-time theming options.

Key Points

• Trestle is now powered by Turbo (8.0.4) & Stimulus (3.2.2) 🎉
• Theming is now done via CSS variables -- a Sass compiler is no longer a required dependency
• Bootstrap has been updated from 4.6.x to 5.3.3
• Font Awesome updated from 5.15.x to 6.5.2
• 🆕 i18n within JS has been streamlined and is handled by fnando/i18n
• 🆕 Propshaft is now supported as an alternative to Sprockets
• 🆕 Magnific Popup has been replaced with PhotoSwipe

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.

If you do come across any more, please comment below and I'll update the list.

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.

Associated PRs

• trestle-auth - Turbo & Bootstrap 5.x updates trestle-auth#52
• trestle-search - Bootstrap 5.x updates trestle-search#53 and Turbo & Bootstrap 5.x updates trestle-search#54
• trestle-tinymce - Hotwire Support trestle-tinymce#12

Updating & Testing

Update your Gemfile to refer to the hotwire branch of the trestle repository, and related gems as required:

gem "trestle", github: "TrestleAdmin/trestle", branch: "hotwire"

gem "trestle-auth", github: "TrestleAdmin/trestle-auth", branch: "hotwire"
gem "trestle-search", github: "TrestleAdmin/trestle-search", branch: "hotwire" # or branch: "hotwire-filters"
gem "trestle-tinymce", github: "TrestleAdmin/trestle-tinymce", branch: "hotwire"

Next Steps

I am currently running these branches in production on a few of my applications and have managed to fix all of the issues I have myself encountered. As such, I'm hoping that this will be able to be merged and released as 0.10.0 fairly soon.

Following that, I'll be releasing a roadmap outlining the remaining features that I'd like to implement before making a 1.0 release.

If you do find any issues while testing this branch, please report them here (or in the relevant repo's PR linked above).