itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-10-02 15:25:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor out htmx 1.x migration guide to its own page

Browse Source
This commit is contained in:
Alexander Petros 2024-01-25 11:14:30 -05:00
parent 01b292ada4
commit 9bf2095886
3 changed files with 61 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
www/content/docs.md
View File

@ -107,7 +107,9 @@ It's worth mentioning that, if you prefer, you can use the [`data-`](https://htm
Htmx is a dependency-free, browser-oriented javascript library. This means that using it is as simple as adding a `<script>`
tag to your document head. No need for complicated build steps or systems.
If you are migrating to htmx from intercooler.js, please see the [migration guide](@/migration-guide.md).
If you are migrating to htmx from intercoolen.js, please see the [intercooler migration guide](@/migration-guide-intercooler.md).
If you are migrating to htmx 2.x from htmx 1.x, please see the [htmx 1.x migration guide](@/migration-guide-htmx-1.md).
### Via A CDN (e.g. unpkg.com)
@ -172,40 +174,6 @@ window.htmx = require('htmx.org');
* Finally, rebuild your bundle
### htmx 1.x to 2.x Upgrade Guide
To upgrade to htmx 2.0 from htmx 1.0, you will need to do the following:
* If you are still using the legacy `hx-ws` and `hx-sse` attributes, please upgrade to the extension versions (available in 1.x)
* Default Changes
* If you want to retain the 1.0 behavior of "smooth scrolling" by default, revert `htmx.config.scrollBehavior` to `'smooth'`
* If you want `DELETE` requests to use a form-encoded body rather than parameters, revert
`htmx.config.methodsThatUseUrlParams` to `["get"]` (it's a little crazy, but `DELETE`, according to the spec, should
use request parameters.)
* If you want to make cross-domain requests with htmx, revert `htmx.config.selfRequestsOnly` to `false`
* Convert any `hx-on` attributes to their `hx-on:` equivalent:
```html
<button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
htmx:afterRequest: alert('Done making a request!')">
Get Info!
</button>
```
becomes:
```html
<button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')"
hx-on:htmx:after-request="alert('Done making a request!')">
Get Info!
</button>
Note that you must use the kebab-case of the event name due to the fact that attributes are case-insensitive in HTML.
```
* The `htmx.makeFragment()` method now **always** returns a `DocumentFragment` rather than either an `Element` or `DocumentFragment`
* If you are using htmx in a module setting, we now provide module-type specific files for all three of the major
JavaScript module types: `/dist/htmx.esm.js`, `/dist/htmx.umd.js` & `/dist/htmx.amd.js`
* htmx 2.0 offers [automatic head merging](#head) with boosted links. If you do not want this behavior, set you can set `htmx.config.head.boosted` to `"none"`
IE is no longer supported in htmx 2.0, but htmx 1.x continues to support IE and will be supported for the foreseeable
future.
## AJAX
The core of htmx is a set of attributes that allow you to issue AJAX requests directly from HTML:

36
www/content/migration-guide-htmx-1.md Normal file
View File

@ -0,0 +1,36 @@
+++
title = "htmx 1.x &rarr; htmx 2.x Migration Guide"
+++
The purpose of this guide is to provide instructions for migrations from htmx 1.x to htmx 2.x.
We place a very high value on backwards compatibility, so in most cases this migrations should require very little, if any, work.
* If you are still using the legacy `hx-ws` and `hx-sse` attributes, please upgrade to the extension versions (available in 1.x)
* Default Changes
* If you want to retain the 1.0 behavior of "smooth scrolling" by default, revert `htmx.config.scrollBehavior` to `'smooth'`
* If you want `DELETE` requests to use a form-encoded body rather than parameters, revert
`htmx.config.methodsThatUseUrlParams` to `["get"]` (it's a little crazy, but `DELETE`, according to the spec, should
use request parameters.)
* If you want to make cross-domain requests with htmx, revert `htmx.config.selfRequestsOnly` to `false`
* Convert any `hx-on` attributes to their `hx-on:` equivalent:
```html
<button hx-get="/info" hx-on="htmx:beforeRequest: alert('Making a request!')
htmx:afterRequest: alert('Done making a request!')">
Get Info!
</button>
```
becomes:
```html
<button hx-get="/info" hx-on:htmx:before-request="alert('Making a request!')"
hx-on:htmx:after-request="alert('Done making a request!')">
Get Info!
</button>
Note that you must use the kebab-case of the event name due to the fact that attributes are case-insensitive in HTML.
```
* The `htmx.makeFragment()` method now **always** returns a `DocumentFragment` rather than either an `Element` or `DocumentFragment`
* If you are using htmx in a module setting, we now provide module-type specific files for all three of the major
JavaScript module types: `/dist/htmx.esm.js`, `/dist/htmx.umd.js` & `/dist/htmx.amd.js`
* htmx 2.0 offers automatic head merging with boosted links. If you do not want this behavior, set you can set `htmx.config.head.boosted` to `"none"`
IE is no longer supported in htmx 2.0, but htmx 1.x continues to support IE and will be supported for the foreseeable future.

0
www/content/migration-guide.md → www/content/migration-guide-intercooler.md
View File