diff options
| author | Nathaniel Sabanski <sabanski.n@gmail.com> | 2022-05-27 08:42:24 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-05-27 09:42:24 -0600 |
| commit | b546c5d69df4f68df7799a195f9bcc49e349eca8 (patch) | |
| tree | 3168d98f0441869db22af58419f26a792452a9c9 | |
| parent | cc6dba15b095fb761dd731266ffbe7be4bc300a4 (diff) | |
| download | htmx-b546c5d69df4f68df7799a195f9bcc49e349eca8.tar.gz htmx-b546c5d69df4f68df7799a195f9bcc49e349eca8.zip | |
Docs: Hotwire / Turbo to htmx Migration Guide (#911)
* Initial commit for migration guide.
* Added notes on Turbo Drive, Turbo Frames, Stimulus
Simplified hx-boost.
Added Hotwire / Turbo migration guide to examples.
Simplified language. Less is more.
Added Redirect after form submission section. Added references to hotwire docs.
Consistency.
First pass on Event interception / pausing.
Naming convention note.
Naming convention notes.
Reference to Event Naming in htmx manual.
Added hyperscript as an alternative solution to event interception / pausing.
Added async notes to Event interception / pausing area.
Simplified language.
Less words.
Added section on disabling buttons during submission.
Less words.
Event naming consistency.
Short is sweet.
Updated hyperscript example.
Comparing htmx and Hotwire.
Revised htmx vs Hotwire / Turbo
Revised htmx vs Hotwire / Turbo
Revision to htmx vs Hotwire / Turbo
Revised htmx vs Hotwire / Turbo
* Clarification of kebab case vs camel case.
| -rw-r--r-- | www/examples.md | 4 | ||||
| -rw-r--r-- | www/migration-guide-hotwire-turbo.md | 56 |
2 files changed, 60 insertions, 0 deletions
diff --git a/www/examples.md b/www/examples.md index 596baae4..6380a41c 100644 --- a/www/examples.md +++ b/www/examples.md @@ -39,3 +39,7 @@ You can copy and paste them and then adjust them for your needs. | [Sortable](/examples/sortable) | Demonstrates how to use htmx with the Sortable.js plugin to implement drag-and-drop reordering | [Updating Other Content](/examples/update-other-content) | Demonstrates how to update content beyond just the target elements | [Confirm](/examples/confirm) | Demonstrates how to implement a custom confirmation dialog with htmx + +## Migrating from Hotwire / Turbo ? + +For common practices see the [Hotwire / Turbo to htmx Migration Guide](/migration-guide-hotwire-turbo). diff --git a/www/migration-guide-hotwire-turbo.md b/www/migration-guide-hotwire-turbo.md new file mode 100644 index 00000000..abe5f1a7 --- /dev/null +++ b/www/migration-guide-hotwire-turbo.md @@ -0,0 +1,56 @@ +--- +layout: layout.njk +title: </> Hotwire / Turbo ➡️ htmx Migration Guide +--- + +# Hotwire / Turbo ➡️ htmx Migration Guide + +The purpose of this guide is to provide common practices for "Hotwire Equivalent" features in htmx. + +* htmx is focused on a set of transparent, highly flexible extensions of html to its logical conclusion as a hypertext. +* Hotwire / Turbo is focused on a smooth out of the box experience, but is more opinionated and less flexible. + +## Turbo Drive + +* `<body hx-boost="true">` to enable a Turbo Drive-like experience. See: [hx-boost](/attributes/hx-boost) +* As with Turbo Drive, if the user does not have javascript enabled, the site will continue to work. See: [Progressive Enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement) +* `hx-boost="false"` is equivalent to `data-turbo="false"` and used to disable boost on specific links or forms. See: [Handbook](https://turbo.hotwired.dev/handbook/drive#disabling-turbo-drive-on-specific-links-or-forms) +* Redirect after form submission (302, 303, 307, 3xx) `hx-target="body" hx-swap="outerHTML" hx-push-url="true"` See: [Handbook](https://turbo.hotwired.dev/handbook/drive#redirecting-after-a-form-submission) +* Disable buttons on form submission See: [Handbook](https://turbo.hotwired.dev/handbook/drive#form-submissions) + * Only disable buttons because `<form>` does not submit disabled fields. See: [MDN: disabled](https://developer.mozilla.org/docs/Web/HTML/Attributes/disabled) +```javascript +addEventListener("submit", (event) => { + event.target.querySelectorAll("button").forEach(node => { node.disabled = true }) +}) +addEventListener("htmx:afterOnLoad", (event) => { + event.target.querySelectorAll("button").forEach(node => { node.disabled = false }) +}) +``` +* Or, [hyperscript](https://hyperscript.org) may be used: `_="on submit toggle @disabled <button/> in me until htmx:afterOnLoad"` See: [Cookbook](/cookbook) + + + +## Turbo Frames + +* Lazy loading: `hx-trigger="load, submit"` See: [Handbook](https://turbo.hotwired.dev/reference/frames#lazy-loaded-frame) + +## Events + +* Intercepting or Pausing Events. `htmx:config-request` is equivalent to `turbo:before-fetch-request` See: [Handbook](https://turbo.hotwired.dev/handbook/drive#pausing-requests) + * `htmx:config-request` is the same as `htmx:configRequest` See: [Event Naming](https://htmx.org/docs/#event_naming) + +```javascript +document.body.addEventListener('htmx:configRequest', (event) => { + event.detail.headers['Authorization'] = `Bearer ${token}` +}) +``` + +* Or, a condition call may be used: `hx-trigger="submit[action(target)]"` See: [hx-trigger](/attributes/hx-trigger) + * Does not currently resolve async calls such as `fetch`. See: https://github.com/bigskysoftware/htmx/issues/912 +* Or, [hyperscript](https://hyperscript.org) may be used: `_="on submit halt the event action(target) trigger ready"` `hx-trigger="ready"` + * Will resolve async calls such as `fetch`. See: [async transparency](https://hyperscript.org/docs/#async) + + +## Stimulus + +* [hyperscript](https://hyperscript.org) is a close analogue and an official companion project to htmx, but the two projects are entirely seperated and can be used exclusively from each other or any other library. |