mirror of
https://github.com/bigskysoftware/htmx.git
synced 2025-09-29 05:51:39 +00:00
Refactor out htmx 1.x migration guide to its own page
This commit is contained in:
Alexander Petros
parent
01b292ada4
commit
9bf2095886
@ -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:
|
||||
@ -637,7 +605,7 @@ You can use this technique to "piggy-back" updates on other requests.
|
||||
|
||||
#### Troublesome Tables
|
||||
|
||||
Table elements can be problematic when combined with out of band swaps, because, by the HTML spec, many can't stand on
|
||||
Table elements can be problematic when combined with out of band swaps, because, by the HTML spec, many can't stand on
|
||||
their own in the DOM (e.g. `<tr>` or `<td>`).
|
||||
|
||||
To avoid this issue you can use a `template` tag to encapsulate these elements:
|
||||
@ -761,7 +729,7 @@ be confirmed. We could add an `unset` directive on it like so:
|
||||
|
||||
The top two buttons would then show a confirm dialog, but the bottom cancel button would not.
|
||||
|
||||
Inheritance can be disabled on a per-element and per-attribute basis using the
|
||||
Inheritance can be disabled on a per-element and per-attribute basis using the
|
||||
[`hx-disinherit`](@/attributes/hx-disinherit.md) attribute.
|
||||
|
||||
If you wish to disable attribute inheritance entirely, you can set the `htmx.config.disableInheritance` configuration
|
||||
@ -983,7 +951,7 @@ HTML into the document at the target specified and with the swap strategy specif
|
||||
|
||||
Sometimes you might want to do nothing in the swap, but still perhaps trigger a client side event ([see below](#response-headers)).
|
||||
|
||||
For this situation, by default, you can return a `204 - No Content` response code, and htmx will ignore the content of
|
||||
For this situation, by default, you can return a `204 - No Content` response code, and htmx will ignore the content of
|
||||
the response.
|
||||
|
||||
In the event of an error response from the server (e.g. a 404 or a 501), htmx will trigger the [`htmx:responseError`](@/events.md#htmx:responseError)
|
||||
@ -1018,7 +986,7 @@ The fields available for response handling configuration on entries in this arra
|
||||
* `target` - A CSS selector specifying an alternative target for the response
|
||||
* `swapOverride` - An alternative swap mechanism for the response
|
||||
|
||||
As an example of how to use this configuration, consider a situation when a server-side framework responds with a
|
||||
As an example of how to use this configuration, consider a situation when a server-side framework responds with a
|
||||
[`422 - Unprocessable Entity`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) response when validation
|
||||
occurs. By default, htmx will ignore the response, since it matches the Regular Expression `[45]..`. You can
|
||||
insert a rule at the start of the `htmx.config.responseHandling` array to override this:
|
||||
@ -1028,7 +996,7 @@ insert a rule at the start of the `htmx.config.responseHandling` array to overri
|
||||
htmx.config.responseHandling.unshift({code:"422", swap: true})
|
||||
```
|
||||
|
||||
You can also completely redefine the array of handlers via the normal configuration mechanisms discussed below.
|
||||
You can also completely redefine the array of handlers via the normal configuration mechanisms discussed below.
|
||||
|
||||
### CORS
|
||||
|
||||
@ -1076,7 +1044,7 @@ For more on the `HX-Trigger` headers, see [`HX-Trigger` Response Headers](@/head
|
||||
|
||||
Submitting a form via htmx has the benefit of no longer needing the [Post/Redirect/Get Pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get).
|
||||
After successfully processing a POST request on the server, you don't need to return a [HTTP 302 (Redirect)](https://en.wikipedia.org/wiki/HTTP_302). You can directly return the new HTML fragment.
|
||||
|
||||
|
||||
### Request Order of Operations {#request-operations}
|
||||
|
||||
The order of operations in a htmx request are:
|
||||
@ -1118,7 +1086,7 @@ the [`hx-validate`](@/attributes/hx-validate.md) attribute to "true".
|
||||
|
||||
### Validation Example
|
||||
|
||||
Here is an example of an input that uses the [`hx-on`](/attributes/hx-on) attribute to catch the
|
||||
Here is an example of an input that uses the [`hx-on`](/attributes/hx-on) attribute to catch the
|
||||
`htmx:validation:validate` event and require that the input have the value `foo`:
|
||||
|
||||
```html
|
||||
@ -1406,7 +1374,7 @@ such as `onClick`:
|
||||
|
||||
This feature allows scripting logic to be co-located with the HTML elements the logic applies to, giving good
|
||||
[Locality of Behaviour (LoB)](/essays/locality-of-behaviour). Unfortunately, HTML only allows `on*` attributes for a fixed
|
||||
number of [specific DOM events](https://www.w3schools.com/tags/ref_eventattributes.asp) (e.g. `onclick`) and
|
||||
number of [specific DOM events](https://www.w3schools.com/tags/ref_eventattributes.asp) (e.g. `onclick`) and
|
||||
doesn't provide a generalized mechanism for responding to arbitrary events on elements.
|
||||
|
||||
In order to address this shortcoming, htmx offers [`hx-on*`](/attributes/hx-on) attributes. These attributes allow
|
||||
@ -1422,8 +1390,8 @@ If we wanted to respond to the `click` event using an `hx-on` attribute, we woul
|
||||
|
||||
So, the string `hx-on`, followed by a colon (or a dash), then by the name of the event.
|
||||
|
||||
For a `click` event, of course, we would recommend sticking with the standard `onclick` attribute. However, consider an
|
||||
htmx-powered button that wishes to add a parameter to a request using the `htmx:config-request` event. This would not
|
||||
For a `click` event, of course, we would recommend sticking with the standard `onclick` attribute. However, consider an
|
||||
htmx-powered button that wishes to add a parameter to a request using the `htmx:config-request` event. This would not
|
||||
be possible using a standard `on*` property, but it can be done using the `hx-on:htmx:config-request` attribute:
|
||||
|
||||
```html
|
||||
@ -1559,7 +1527,7 @@ to generate a different `ETag` for each content.
|
||||
|
||||
## Security
|
||||
|
||||
htmx allows you to define logic directly in your DOM. This has a number of advantages, the largest being
|
||||
htmx allows you to define logic directly in your DOM. This has a number of advantages, the largest being
|
||||
[Locality of Behavior](@/essays/locality-of-behaviour.md), which makes your system easier to understand and
|
||||
maintain.
|
||||
|
||||
@ -1569,8 +1537,8 @@ ends.
|
||||
|
||||
### Rule 1: Escape All User Content
|
||||
|
||||
The first rule of HTML-based web development has always been: *do not trust input from the user*. You should escape all
|
||||
3rd party, untrusted content that is injected into your site. This is to prevent, among other issues,
|
||||
The first rule of HTML-based web development has always been: *do not trust input from the user*. You should escape all
|
||||
3rd party, untrusted content that is injected into your site. This is to prevent, among other issues,
|
||||
[XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting).
|
||||
|
||||
There is extensive documentation on XSS and how to prevent it on the excellent [OWASP Website](https://owasp.org/www-community/attacks/xss/),
|
||||
@ -1585,21 +1553,21 @@ mechanism in their templating language. This can be done for good reasons, but
|
||||
from a 3rd party then it _must_ be scrubbed, including removing attributes starting with `hx-` and `data-hx`, as well as
|
||||
inline `<script>` tags, etc.
|
||||
|
||||
If you are injecting raw HTML and doing your own escaping, a best practice is to *whitelist* the attributes and tags you
|
||||
allow, rather than to blacklist the ones you disallow.
|
||||
If you are injecting raw HTML and doing your own escaping, a best practice is to *whitelist* the attributes and tags you
|
||||
allow, rather than to blacklist the ones you disallow.
|
||||
|
||||
### htmx Security Tools
|
||||
|
||||
Of course, bugs happen and developers are not perfect, so it is good to have a layered approach to security for
|
||||
your web application, and htmx provides tools to help secure your application as well.
|
||||
your web application, and htmx provides tools to help secure your application as well.
|
||||
|
||||
Let's take a look at them.
|
||||
|
||||
#### `hx-disable`
|
||||
|
||||
The first tool htmx provides to help further secure your application is the [`hx-disable`](/attributes/hx-disable)
|
||||
The first tool htmx provides to help further secure your application is the [`hx-disable`](/attributes/hx-disable)
|
||||
attribute. This attribute will prevent processing of all htmx attributes on a given element, and on all elements within
|
||||
it. So, for example, if you were including raw HTML content in a template (again, this is not recommended!) then you
|
||||
it. So, for example, if you were including raw HTML content in a template (again, this is not recommended!) then you
|
||||
could place a div around the content with the `hx-disable` attribute on it:
|
||||
|
||||
```html
|
||||
@ -1615,15 +1583,15 @@ element, it will not be processed by htmx.
|
||||
#### `hx-history`
|
||||
|
||||
Another security consideration is htmx history cache. You may have pages that have sensitive data that you do not
|
||||
want stored in the users `localStorage` cache. You can omit a given page from the history cache by including the
|
||||
[`hx-history`](/attributes/hx-history) attribute anywhere on the page, and setting its value to `false`.
|
||||
want stored in the users `localStorage` cache. You can omit a given page from the history cache by including the
|
||||
[`hx-history`](/attributes/hx-history) attribute anywhere on the page, and setting its value to `false`.
|
||||
|
||||
#### Configuration Options
|
||||
|
||||
htmx also provides configuration options related to security:
|
||||
|
||||
* `htmx.config.selfRequestsOnly` - if set to `true`, only requests to the same domain as the current document will be allowed
|
||||
* `htmx.config.allowScriptTags` - htmx will process `<script>` tags found in new content it loads. If you wish to disable
|
||||
* `htmx.config.allowScriptTags` - htmx will process `<script>` tags found in new content it loads. If you wish to disable
|
||||
this behavior you can set this configuration variable to `false`
|
||||
* `htmx.config.historyCacheSize` - can be set to `0` to avoid storing any HTML in the `localStorage` cache
|
||||
* `htmx.config.allowEval` - can be set to `false` to disable all features of htmx that rely on eval:
|
||||
@ -1655,7 +1623,7 @@ document.body.addEventListener('htmx:validateUrl', function (evt) {
|
||||
|
||||
### CSP Options
|
||||
|
||||
Browsers also provide tools for further securing your web application. The most powerful tool available is a
|
||||
Browsers also provide tools for further securing your web application. The most powerful tool available is a
|
||||
[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). Using a CSP you can tell the
|
||||
browser to, for example, not issue requests to non-origin hosts, to not evaluate inline script tags, etc.
|
||||
|
||||
|
||||
36
www/content/migration-guide-htmx-1.md
Normal file
36
www/content/migration-guide-htmx-1.md
Normal file
@ -0,0 +1,36 @@
|
||||
+++
|
||||
title = "htmx 1.x → 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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user