diff options
Diffstat (limited to 'www/content')
| -rw-r--r-- | www/content/_index.md | 6 | ||||
| -rw-r--r-- | www/content/api.md | 3 | ||||
| -rw-r--r-- | www/content/attributes/hx-disabled-elt.md | 16 | ||||
| -rw-r--r-- | www/content/attributes/hx-include.md | 17 | ||||
| -rw-r--r-- | www/content/attributes/hx-indicator.md | 13 | ||||
| -rw-r--r-- | www/content/attributes/hx-vals.md | 1 | ||||
| -rw-r--r-- | www/content/docs.md | 110 | ||||
| -rw-r--r-- | www/content/essays/view-transitions.md | 2 | ||||
| -rw-r--r-- | www/content/events.md | 38 | ||||
| -rw-r--r-- | www/content/examples/modal-custom.md | 4 | ||||
| -rw-r--r-- | www/content/examples/modal-uikit.md | 2 | ||||
| -rw-r--r-- | www/content/examples/tabs-javascript.md | 2 | ||||
| -rw-r--r-- | www/content/extensions/head-support.md | 8 | ||||
| -rw-r--r-- | www/content/extensions/htmx-1-compat.md | 8 | ||||
| -rw-r--r-- | www/content/extensions/idiomorph.md | 2 | ||||
| -rw-r--r-- | www/content/extensions/preload.md | 8 | ||||
| -rw-r--r-- | www/content/extensions/response-targets.md | 8 | ||||
| -rw-r--r-- | www/content/extensions/sse.md | 8 | ||||
| -rw-r--r-- | www/content/extensions/ws.md | 8 | ||||
| -rw-r--r-- | www/content/reference.md | 77 |
20 files changed, 209 insertions, 132 deletions
diff --git a/www/content/_index.md b/www/content/_index.md index 365b8694..c6c42fc6 100644 --- a/www/content/_index.md +++ b/www/content/_index.md @@ -104,7 +104,7 @@ directly in HTML, using [attributes](@/reference.md#attributes), so you can buil [modern user interfaces](@/examples/_index.md) with the [simplicity](https://en.wikipedia.org/wiki/HATEOAS) and [power](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) of hypertext -htmx is small ([~14k min.gz'd](https://unpkg.com/htmx.org/dist/)), +htmx is small ([~14k min.gz'd](https://cdn.jsdelivr.net/npm/htmx.org/dist/)), [dependency-free](https://github.com/bigskysoftware/htmx/blob/master/package.json), [extendable](https://htmx.org/extensions) & has **reduced** code base sizes by [67% when compared with react](@/essays/a-real-world-react-to-htmx-port.md) @@ -120,7 +120,7 @@ By removing these constraints, htmx completes HTML as a [hypertext](https://en.w <h2>quick start</h2> ```html - <script src="https://unpkg.com/htmx.org@2.0.4"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js"></script> <!-- have a button POST a click via AJAX --> <button hx-post="/clicked" hx-swap="outerHTML"> Click Me @@ -235,7 +235,7 @@ Thank you to all our generous <a href="https://github.com/sponsors/bigskysoftwar </a> </div> <div> - <a data-github-account="sekunho" href="https://twitter.com/sekunho_/"><img src="/img/sekun-doggo.jpg" alt="Hiro The Doggo" style="border: 2px solid lightgray; border-radius:20px"></a> + <a data-github-account="sekunho" href="https://tacohiro.systems/"><img src="/img/sekun-doggo.jpg" alt="Hiro The Doggo" style="border: 2px solid lightgray; border-radius:20px"></a> </div> <div> <a href="https://dasfilter.shop/pages/affiliates"> diff --git a/www/content/api.md b/www/content/api.md index 5ea9a63c..d72c5974 100644 --- a/www/content/api.md +++ b/www/content/api.md @@ -141,7 +141,8 @@ Note that using a [meta tag](@/docs.md#config) is the preferred mechanism for se * `scrollIntoViewOnBoost:true` - boolean: whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. * `triggerSpecsCache:null` - object: the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) * `htmx.config.responseHandling:[...]` - HtmxResponseHandlingConfig[]: the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error -* `htmx.config.allowNestedOobSwaps:true` - boolean: whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). +* `htmx.config.allowNestedOobSwaps:true` - boolean: whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). +* `htmx.config.historyRestoreAsHxRequest:true` - Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses ##### Example diff --git a/www/content/attributes/hx-disabled-elt.md b/www/content/attributes/hx-disabled-elt.md index bdae9394..3c6845ba 100644 --- a/www/content/attributes/hx-disabled-elt.md +++ b/www/content/attributes/hx-disabled-elt.md @@ -32,7 +32,8 @@ Here is an example with a button that will disable itself during a request: When a request is in flight, this will cause the button to be marked with [the `disabled` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled), which will prevent further clicks from occurring. -The `hx-disabled-elt` attribute also supports specifying multiple CSS selectors separated by commas to disable multiple elements during the request. Here is an example that disables buttons and text input fields of a particular form during the request: +The `hx-disabled-elt` attribute also supports specifying multiple CSS selectors separated by commas to disable multiple + elements during the request. Here is an example that disables buttons and text input fields of a particular form during the request: ```html <form hx-post="/example" hx-disabled-elt="find input[type='text'], find button"> @@ -41,6 +42,19 @@ The `hx-disabled-elt` attribute also supports specifying multiple CSS selectors </form> ``` +Note that you can also use the `inherit` keyword to inherit parent values for a disabled elements and add additional +disabled element CSS selectors: + +```html +<main hx-disabled-elt="#logout-button"> + ... + <form hx-post="/example" hx-disabled-elt="inherit, find input[type='text'], find button"> + <input type="text" placeholder="Type here..."> + <button type="submit">Send</button> + </form> +</main> +``` + ## Notes * `hx-disabled-elt` is inherited and can be placed on a parent element diff --git a/www/content/attributes/hx-include.md b/www/content/attributes/hx-include.md index cb3ab5ee..bbedbbb6 100644 --- a/www/content/attributes/hx-include.md +++ b/www/content/attributes/hx-include.md @@ -31,7 +31,20 @@ Here is an example that includes a separate input value: This is a little contrived as you would typically enclose both of these elements in a `form` and submit the value automatically, but it demonstrates the concept. -Note that if you include a non-input element, all input elements enclosed in that element will be included. +Note that you can also use the `inherit` keyword to inherit parent values for inclusion and add additional values: + +```html +<main hx-include="#hidden-input"> + ... + <button hx-post="/example" hx-include="inherit, [name='email']"> + Post It! + </button> + Enter email: <input name="email" type="email"/> +</main> +``` + + +Finally, note that if you include a non-input element, all input elements enclosed in that element will be included. ## Notes @@ -52,4 +65,4 @@ Note that if you include a non-input element, all input elements enclosed in tha to [document.querySelectorAll](https://developer.mozilla.org/docs/Web/API/Document/querySelectorAll) and will include multiple elements, while the extended selectors such as `find` or `next` only return a single element at most to include -* `hx-include` will ignore disabled inputs
\ No newline at end of file +* `hx-include` will ignore disabled inputs diff --git a/www/content/attributes/hx-indicator.md b/www/content/attributes/hx-indicator.md index 1c2358b1..46a8094c 100644 --- a/www/content/attributes/hx-indicator.md +++ b/www/content/attributes/hx-indicator.md @@ -25,6 +25,19 @@ Here is an example with a spinner adjacent to the button: </div> ``` +Note that you can also use the `inherit` keyword to inherit parent values for an indicator and add additional indicator +CSS selectors: + +```html +<main hx-indicator="#global-indicator"> + ... + <button hx-post="/example" hx-indicator="inherit, #spinner"> + Post It! + </button> + <img id="spinner" class="htmx-indicator" src="/img/bars.svg"/> +</main> +``` + When a request is in flight, this will cause the `htmx-request` class to be added to the `#spinner` image. The image also has the `htmx-indicator` class on it, which defines an opacity transition that will show the spinner: diff --git a/www/content/attributes/hx-vals.md b/www/content/attributes/hx-vals.md index df3675a4..ebe02852 100644 --- a/www/content/attributes/hx-vals.md +++ b/www/content/attributes/hx-vals.md @@ -45,3 +45,4 @@ In this example, if `foo()` returns an object like `{name: "John", age: 30}`, bo * `hx-vals` is inherited and can be placed on a parent element. * A child declaration of a variable overrides a parent declaration. * Input values with the same name will be overridden by variable declarations. +* When using `javascript:`, `this` refers to the element with the `hx-vals` attribute diff --git a/www/content/docs.md b/www/content/docs.md index d28c3173..dfba110a 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -117,19 +117,19 @@ If you are migrating to htmx from intercooler.js, please see the [intercooler mi 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. There is no need for a build system to use it. -### Via A CDN (e.g. unpkg.com) +### Via A CDN (e.g. jsDelivr) The fastest way to get going with htmx is to load it via a CDN. You can simply add this to your head tag and get going: ```html -<script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> +<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-t4DxZSyQK+0Uv4jzy5B0QyHyWQD2GFURUmxKMBVww9+e2EJ0ei/vCvv7+79z0fkr" crossorigin="anonymous"></script> ``` An unminified version is also available as well: ```html -<script src="https://unpkg.com/htmx.org@2.0.4/dist/htmx.js" integrity="sha384-oeUn82QNXPuVkGCkcrInrS1twIxKhkZiFfr2TdiuObZ3n3yIeMiqcRzkIcguaof1" crossorigin="anonymous"></script> +<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.js" integrity="sha384-5DNWP7/6VfmFjDrEgZ0MwJiuIz0/juUdZwgMAqxCaHBd/BH8MF4yWxDv+mo/o9CG" crossorigin="anonymous"></script> ``` While the CDN approach is extremely simple, you may want to consider @@ -139,7 +139,7 @@ While the CDN approach is extremely simple, you may want to consider The next easiest way to install htmx is to simply copy it into your project. -Download `htmx.min.js` [from unpkg.com](https://unpkg.com/htmx.org@2.0.4/dist/htmx.min.js) and add it to the appropriate directory in your project +Download `htmx.min.js` [from jsDelivr](https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js) and add it to the appropriate directory in your project and include it where necessary with a `<script>` tag: ```html @@ -151,7 +151,7 @@ and include it where necessary with a `<script>` tag: For npm-style build systems, you can install htmx via [npm](https://www.npmjs.com/): ```sh -npm install htmx.org@2.0.4 +npm install htmx.org@2.0.5 ``` After installing, you’ll need to use appropriate tooling to use `node_modules/htmx.org/dist/htmx.js` (or `.min.js`). @@ -643,8 +643,8 @@ will include the values of all inputs within it. As with HTML forms, the `name` attribute of the input is used as the parameter name in the request that htmx sends. -Additionally, if the element causes a non-`GET` request, the values of all the inputs of the nearest enclosing form -will be included. +Additionally, if the element causes a non-`GET` request, the values of all the inputs of the associated form will be +included (typically this is the nearest enclosing form, but could be different if e.g. `<button form="associated-form">` is used). If you wish to include the values of other elements, you can use the [hx-include](@/attributes/hx-include.md) attribute with a CSS selector of all the elements whose values you want to include in the request. @@ -860,8 +860,9 @@ It then does the swap and pushes a new location onto the history stack. When a user hits the back button, htmx will retrieve the old content from storage and swap it back into the target, simulating "going back" to the previous state. If the location is not found in the cache, htmx will make an ajax request to the given URL, with the header `HX-History-Restore-Request` set to true, and expects back the HTML needed -for the entire page. Alternatively, if the `htmx.config.refreshOnHistoryMiss` config variable is set to true, it will -issue a hard browser refresh. +for the entire page. You should always set `htmx.config.historyRestoreAsHxRequest` to false to prevent the `HX-Request` header +which can then be safely used to respond with partials. Alternatively, if the `htmx.config.refreshOnHistoryMiss` config variable +is set to true, it will issue a hard browser refresh. **NOTE:** If you push a URL into the history, you **must** be able to navigate to that URL and get a full page back! A user could copy and paste the URL into an email, or new tab. Additionally, htmx will need the entire page when restoring @@ -1022,7 +1023,7 @@ htmx includes a number of useful headers in requests: | `HX-Current-URL` | the current URL of the browser | `HX-History-Restore-Request` | "true" if the request is for history restoration after a miss in the local history cache | `HX-Prompt` | the user response to an [hx-prompt](@/attributes/hx-prompt.md) -| `HX-Request` | always "true" +| `HX-Request` | always "true" except on history restore requests if `htmx.config.historyRestoreAsHxRequest' disabled | `HX-Target` | the `id` of the target element if it exists | `HX-Trigger-Name` | the `name` of the triggered element if it exists | `HX-Trigger` | the `id` of the triggered element if it exists @@ -1139,15 +1140,15 @@ You can see all available extensions on the [Extensions](/extensions) page. The fastest way to install htmx extensions created by others is to load them via a CDN. Remember to always include the core htmx library before the extensions and [enable the extension](#enabling-extensions). For example, if you would like to use the [response-targets](/extensions/response-targets) extension, you can add this to your head tag: ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> - <script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-t4DxZSyQK+0Uv4jzy5B0QyHyWQD2GFURUmxKMBVww9+e2EJ0ei/vCvv7+79z0fkr" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx-ext-response-targets@2.0.2" integrity="sha384-UMuM7P2CPg9i2/dfvBlAeqjXITmEWe9k17Mp9X07Z4jXPN21Ychng569t+sUL8oa" crossorigin="anonymous"></script> </head> <body hx-ext="extension-name"> ... ``` -An unminified version is also available at `https://unpkg.com/htmx-ext-extension-name/dist/extension-name.js` (replace `extension-name` with the name of the extension). +An unminified version is also available at `https://cdn.jsdelivr.net/npm/htmx-ext-extension-name/dist/extension-name.js` (replace `extension-name` with the name of the extension). -While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install htmx extensions is to simply copy them into your project. Download the extension from `https://unpkg.com/htmx-ext-extension-name` (replace `extension-name` with the name of the extension) e.g., https://unpkg.com/htmx-ext-response-targets. Then add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install htmx extensions is to simply copy them into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-extension-name` (replace `extension-name` with the name of the extension) e.g., https://cdn.jsdelivr.net/npm/htmx-ext-response-targets. Then add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. For npm-style build systems, you can install htmx extensions via [npm](https://www.npmjs.com/) (replace `extension-name` with the name of the extension): ```shell @@ -1163,7 +1164,7 @@ import `htmx.org`; import `htmx-ext-extension-name`; // replace `extension-name` with the name of the extension ``` -Note: [Idiomorph](/extensions/idiomorph) does not follow the naming convention of htmx extensions. Use `idiomorph` instead of `htmx-ext-idiomorph`. For example, `https://unpkg.com/idiomorph` or `npm install idiomorph`. +Note: [Idiomorph](/extensions/idiomorph) does not follow the naming convention of htmx extensions. Use `idiomorph` instead of `htmx-ext-idiomorph`. For example, `https://cdn.jsdelivr.net/npm/idiomorph` or `npm install idiomorph`. Note: Community extensions hosted outside this repository might have different installation instructions. Please check the corresponding repository for set-up guidance. @@ -1564,7 +1565,8 @@ response HTTP header. For example, if your server renders the full HTML when the `HX-Request` header is missing or `false`, and it renders a fragment of that HTML when `HX-Request: true`, you need to add `Vary: HX-Request`. That causes the cache to be keyed based on a composite of the response URL and the `HX-Request` request header — -rather than being based just on the response URL. +rather than being based just on the response URL. Always disable `htmx.config.historyRestoreAsHxRequest` +so that these history full HTML requests are not cached with partial fragment responses. If you are unable (or unwilling) to use the `Vary` header, you can alternatively set the configuration parameter `getCacheBusterParam` to `true`. If this configuration variable is set, htmx will include a cache-busting parameter @@ -1717,44 +1719,44 @@ listed below: <div class="info-table"> -| Config Variable | Info | -|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `htmx.config.historyEnabled` | defaults to `true`, really only useful for testing | -| `htmx.config.historyCacheSize` | defaults to 10 | -| `htmx.config.refreshOnHistoryMiss` | defaults to `false`, if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request | -| `htmx.config.defaultSwapStyle` | defaults to `innerHTML` | -| `htmx.config.defaultSwapDelay` | defaults to 0 | -| `htmx.config.defaultSettleDelay` | defaults to 20 | -| `htmx.config.includeIndicatorStyles` | defaults to `true` (determines if the indicator styles are loaded) | -| `htmx.config.indicatorClass` | defaults to `htmx-indicator` | -| `htmx.config.requestClass` | defaults to `htmx-request` | -| `htmx.config.addedClass` | defaults to `htmx-added` | -| `htmx.config.settlingClass` | defaults to `htmx-settling` | -| `htmx.config.swappingClass` | defaults to `htmx-swapping` | -| `htmx.config.allowEval` | defaults to `true`, can be used to disable htmx's use of eval for certain features (e.g. trigger filters) | -| `htmx.config.allowScriptTags` | defaults to `true`, determines if htmx will process script tags found in new content | -| `htmx.config.inlineScriptNonce` | defaults to `''`, meaning that no nonce will be added to inline scripts | -| `htmx.config.attributesToSettle` | defaults to `["class", "style", "width", "height"]`, the attributes to settle during the settling phase | -| `htmx.config.inlineStyleNonce` | defaults to `''`, meaning that no nonce will be added to inline styles | -| `htmx.config.useTemplateFragments` | defaults to `false`, HTML template tags for parsing content from the server (not IE11 compatible!) | -| `htmx.config.wsReconnectDelay` | defaults to `full-jitter` | -| `htmx.config.wsBinaryType` | defaults to `blob`, the [type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection | -| `htmx.config.disableSelector` | defaults to `[hx-disable], [data-hx-disable]`, htmx will not process elements with this attribute on it or a parent | -| `htmx.config.withCredentials` | defaults to `false`, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates | -| `htmx.config.timeout` | defaults to 0, the number of milliseconds a request can take before automatically being terminated | -| `htmx.config.scrollBehavior` | defaults to 'instant', the scroll behavior when using the [show](@/attributes/hx-swap.md#scrolling-scroll-show) modifier with `hx-swap`. The allowed values are `instant` (scrolling should happen instantly in a single jump), `smooth` (scrolling should animate smoothly) and `auto` (scroll behavior is determined by the computed value of [scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)). | -| `htmx.config.defaultFocusScroll` | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier. | -| `htmx.config.getCacheBusterParam` | defaults to false, if set to true htmx will append the target element to the `GET` request in the format `org.htmx.cache-buster=targetElementId` | -| `htmx.config.globalViewTransitions` | if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content. | -| `htmx.config.methodsThatUseUrlParams` | defaults to `["get", "delete"]`, htmx will format requests with these methods by encoding their parameters in the URL, not the request body | -| `htmx.config.selfRequestsOnly` | defaults to `true`, whether to only allow AJAX requests to the same domain as the current document | -| `htmx.config.ignoreTitle` | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content | -| `htmx.config.disableInheritance` | disables attribute inheritance in htmx, which can then be overridden by the [`hx-inherit`](@/attributes/hx-inherit.md) attribute | -| `htmx.config.scrollIntoViewOnBoost` | defaults to `true`, whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. | -| `htmx.config.triggerSpecsCache` | defaults to `null`, the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) | -| `htmx.config.responseHandling` | the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error | -| `htmx.config.allowNestedOobSwaps` | defaults to `true`, whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). | - +| Config Variable | Info | +|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `htmx.config.historyEnabled` | defaults to `true`, really only useful for testing | +| `htmx.config.historyCacheSize` | defaults to 10 | +| `htmx.config.refreshOnHistoryMiss` | defaults to `false`, if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request | +| `htmx.config.defaultSwapStyle` | defaults to `innerHTML` | +| `htmx.config.defaultSwapDelay` | defaults to 0 | +| `htmx.config.defaultSettleDelay` | defaults to 20 | +| `htmx.config.includeIndicatorStyles` | defaults to `true` (determines if the indicator styles are loaded) | +| `htmx.config.indicatorClass` | defaults to `htmx-indicator` | +| `htmx.config.requestClass` | defaults to `htmx-request` | +| `htmx.config.addedClass` | defaults to `htmx-added` | +| `htmx.config.settlingClass` | defaults to `htmx-settling` | +| `htmx.config.swappingClass` | defaults to `htmx-swapping` | +| `htmx.config.allowEval` | defaults to `true`, can be used to disable htmx's use of eval for certain features (e.g. trigger filters) | +| `htmx.config.allowScriptTags` | defaults to `true`, determines if htmx will process script tags found in new content | +| `htmx.config.inlineScriptNonce` | defaults to `''`, meaning that no nonce will be added to inline scripts | +| `htmx.config.attributesToSettle` | defaults to `["class", "style", "width", "height"]`, the attributes to settle during the settling phase | +| `htmx.config.inlineStyleNonce` | defaults to `''`, meaning that no nonce will be added to inline styles | +| `htmx.config.useTemplateFragments` | defaults to `false`, HTML template tags for parsing content from the server (not IE11 compatible!) | +| `htmx.config.wsReconnectDelay` | defaults to `full-jitter` | +| `htmx.config.wsBinaryType` | defaults to `blob`, the [type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection | +| `htmx.config.disableSelector` | defaults to `[hx-disable], [data-hx-disable]`, htmx will not process elements with this attribute on it or a parent | +| `htmx.config.withCredentials` | defaults to `false`, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates | +| `htmx.config.timeout` | defaults to 0, the number of milliseconds a request can take before automatically being terminated | +| `htmx.config.scrollBehavior` | defaults to 'instant', the scroll behavior when using the [show](@/attributes/hx-swap.md#scrolling-scroll-show) modifier with `hx-swap`. The allowed values are `instant` (scrolling should happen instantly in a single jump), `smooth` (scrolling should animate smoothly) and `auto` (scroll behavior is determined by the computed value of [scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)). | +| `htmx.config.defaultFocusScroll` | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier. | +| `htmx.config.getCacheBusterParam` | defaults to false, if set to true htmx will append the target element to the `GET` request in the format `org.htmx.cache-buster=targetElementId` | +| `htmx.config.globalViewTransitions` | if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content. | +| `htmx.config.methodsThatUseUrlParams` | defaults to `["get", "delete"]`, htmx will format requests with these methods by encoding their parameters in the URL, not the request body | +| `htmx.config.selfRequestsOnly` | defaults to `true`, whether to only allow AJAX requests to the same domain as the current document | +| `htmx.config.ignoreTitle` | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content | +| `htmx.config.disableInheritance` | disables attribute inheritance in htmx, which can then be overridden by the [`hx-inherit`](@/attributes/hx-inherit.md) attribute | +| `htmx.config.scrollIntoViewOnBoost` | defaults to `true`, whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. | +| `htmx.config.triggerSpecsCache` | defaults to `null`, the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) | +| `htmx.config.responseHandling` | the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error | +| `htmx.config.allowNestedOobSwaps` | defaults to `true`, whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). | +| `htmx.config.historyRestoreAsHxRequest`| defaults to `true`, Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses | </div> You can set them directly in javascript, or you can use a `meta` tag: diff --git a/www/content/essays/view-transitions.md b/www/content/essays/view-transitions.md index 582dba70..99547020 100644 --- a/www/content/essays/view-transitions.md +++ b/www/content/essays/view-transitions.md @@ -88,7 +88,7 @@ Now, that's my kind of API. As luck would have it, it's trivial to wrap this API around the regular htmx swapping model, which allows us to start exploring View Transitions in htmx, even before it's generally available in HTML! -And, as of [htmx 1.9.0](https://unpkg.com/htmx.org@1.9.0), you can start experimenting with the API by adding the +And, as of [htmx 1.9.0](https://cdn.jsdelivr.net/npm/htmx.org@1.9.0), you can start experimenting with the API by adding the `transition:true` attribute to an [`hx-swap`](/attributes/hx-swap) attribute. ## A Practical Example diff --git a/www/content/events.md b/www/content/events.md index 42bd8eba..47aa460f 100644 --- a/www/content/events.md +++ b/www/content/events.md @@ -262,16 +262,36 @@ This event is triggered when an attempt to save the cache to `localStorage` fail * `detail.cause` - the `Exception` that was thrown when attempting to save history to `localStorage` +### Event - `htmx:historyCacheHit` {#htmx:historyCacheHit} + +This event is triggered when a cache hit occurs when restoring history + +You can prevent the history restoration via `preventDefault()` to allow alternative restore handling. +You can also override the details of the history restoration request in this event if required + +##### Details + +* `detail.historyElt` - the history element or body that will get replaced +* `detail.item.content` - the content of the cache that will be swapped in +* `detail.item.title` - the page title to update from the cache +* `detail.path` - the path and query of the page being restored +* `detial.swapSpec` - the swapSpec to be used containing the defatul swapStyle='innerHTML' + ### Event - `htmx:historyCacheMiss` {#htmx:historyCacheMiss} This event is triggered when a cache miss occurs when restoring history +You can prevent the history restoration via `preventDefault()` to allow alternative restore handling. +You can also modify the xhr request or other details before it makes the the request to restore history + ##### Details +* `detail.historyElt` - the history element or body that will get replaced * `detail.xhr` - the `XMLHttpRequest` that will retrieve the remote content for restoration * `detail.path` - the path and query of the page being restored +* `detial.swapSpec` - the swapSpec to be used containing the defatul swapStyle='innerHTML' -### Event - `htmx:historyCacheMissError` {#htmx:historyCacheMissError} +### Event - `htmx:historyCacheMissLoadError` {#htmx:historyCacheMissLoadError} This event is triggered when a cache miss occurs and a response has been retrieved from the server for the content to restore, but the response is an error (e.g. `404`) @@ -286,10 +306,15 @@ for the content to restore, but the response is an error (e.g. `404`) This event is triggered when a cache miss occurs and a response has been retrieved successfully from the server for the content to restore +You can modify the details before it makes the swap to restore the history + ##### Details +* `detail.historyElt` - the history element or body that will get replaced * `detail.xhr` - the `XMLHttpRequest` * `detail.path` - the path and query of the page being restored +* `detail.response` - the response text that will be swapped in +* `detial.swapSpec` - the swapSpec to be used containing the defatul swapStyle='innerHTML' ### Event - `htmx:historyRestore` {#htmx:historyRestore} @@ -298,15 +323,20 @@ This event is triggered when htmx handles a history restoration action ##### Details * `detail.path` - the path and query of the page being restored +* `detail.cacheMiss` - set `true` if restore was a cache miss +* `detail.serverResponse` - with cache miss has the response text replaced +* `detail.item` - with cache hit the cache details that was restored ### Event - `htmx:beforeHistorySave` {#htmx:beforeHistorySave} -This event is triggered before the content is saved in the history api. +This event is triggered before the content is saved in the history cache. + +You can modify the contents of the historyElt to remove 3rd party javascript changes so a clean copy of the content can be backed up to the history cache ##### Details -* `detail.path` - the path and query of the page being restored -* `detail.historyElt` - the history element being restored into +* `detail.path` - the path and query of the page being saved +* `detail.historyElt` - the history element about to be saved ### Event - `htmx:load` {#htmx:load} diff --git a/www/content/examples/modal-custom.md b/www/content/examples/modal-custom.md index 8997da95..7cd71259 100644 --- a/www/content/examples/modal-custom.md +++ b/www/content/examples/modal-custom.md @@ -132,8 +132,8 @@ example. } ``` -<script src="https://unpkg.com/htmx.org"></script> -<script src="https://unpkg.com/hyperscript.org"></script> +<script src="https://cdn.jsdelivr.net/npm/htmx.org"></script> +<script src="https://cdn.jsdelivr.net/npm/hyperscript.org"></script> <script type="text/javascript"> //========================================================================= diff --git a/www/content/examples/modal-uikit.md b/www/content/examples/modal-uikit.md index 25fbd67c..5b6507d7 100644 --- a/www/content/examples/modal-uikit.md +++ b/www/content/examples/modal-uikit.md @@ -89,7 +89,7 @@ window.document.getElementById("cancelButton").addEventListener("click", functio @import "https://cdnjs.cloudflare.com/ajax/libs/uikit/3.5.9/css/uikit-core.min.css"; </style> -<script src="https://unpkg.com/hyperscript.org"></script> +<script src="https://cdn.jsdelivr.net/npm/hyperscript.org"></script> <script> //========================================================================= // Fake Server Side Code diff --git a/www/content/examples/tabs-javascript.md b/www/content/examples/tabs-javascript.md index 5b6536dc..b36fd85a 100644 --- a/www/content/examples/tabs-javascript.md +++ b/www/content/examples/tabs-javascript.md @@ -49,7 +49,7 @@ when the content is swapped into the DOM. <div id="tab-contents" role="tabpanel" hx-get="/tab1" hx-trigger="load"></div> -<script src="https://unpkg.com/hyperscript.org"></script> +<script src="https://cdn.jsdelivr.net/npm/hyperscript.org"></script> <script> onGet("/tab1", function() { return ` diff --git a/www/content/extensions/head-support.md b/www/content/extensions/head-support.md index 67c1aaef..5eb8b324 100644 --- a/www/content/extensions/head-support.md +++ b/www/content/extensions/head-support.md @@ -18,15 +18,15 @@ a feature of the library. This extension addresses that shortcoming. The fastest way to install `head-support` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> - <script src="https://unpkg.com/htmx-ext-head-support@2.0.2" integrity="sha384-cvMqHzjCJsOHgGuyB3sWXaUSv/Krm0BdzjuI1rtkjCbL1l1oHJx+cHyVRJhyuEz0" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx-ext-head-support@2.0.2" integrity="sha384-cvMqHzjCJsOHgGuyB3sWXaUSv/Krm0BdzjuI1rtkjCbL1l1oHJx+cHyVRJhyuEz0" crossorigin="anonymous"></script> </head> <body hx-ext="head-support"> ... ``` -An unminified version is also available at https://unpkg.com/htmx-ext-head-support/dist/head-support.js. +An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-head-support/dist/head-support.js. -While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `head-support` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-head-support`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `head-support` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-head-support`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. For npm-style build systems, you can install `head-support` via [npm](https://www.npmjs.com/): ```shell diff --git a/www/content/extensions/htmx-1-compat.md b/www/content/extensions/htmx-1-compat.md index 2e157c02..19fb25a8 100644 --- a/www/content/extensions/htmx-1-compat.md +++ b/www/content/extensions/htmx-1-compat.md @@ -9,15 +9,15 @@ The `htmx-1-compat` extension allows you to almost seamlessly upgrade from htmx The fastest way to install `htmx-1-compat` is to load it via a CDN. Remember to always include the core htmx library before the extension and enable the extension. ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> - <script src="https://unpkg.com/htmx-ext-htmx-1-compat@2.0.0" integrity="sha384-lcvVWaNjF5zPPUeeWmC0OkJ2MLqoWLlkAabuGm+EuMSTfGo5WRyHrNaAp0cJr9Pg" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx-ext-htmx-1-compat@2.0.0" integrity="sha384-lcvVWaNjF5zPPUeeWmC0OkJ2MLqoWLlkAabuGm+EuMSTfGo5WRyHrNaAp0cJr9Pg" crossorigin="anonymous"></script> </head> <body hx-ext="htmx-1-compat"> ... ``` -An unminified version is also available at https://unpkg.com/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js. +An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-htmx-1-compat/dist/htmx-1-compat.js. -While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `htmx-1-compat` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-htmx-1-compat`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `htmx-1-compat` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-htmx-1-compat`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. For npm-style build systems, you can install `htmx-1-compat` via [npm](https://www.npmjs.com/): ```shell diff --git a/www/content/extensions/idiomorph.md b/www/content/extensions/idiomorph.md index 60ea0a83..43b41723 100644 --- a/www/content/extensions/idiomorph.md +++ b/www/content/extensions/idiomorph.md @@ -15,7 +15,7 @@ extension. The fastest way to install `idiomorph` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js@2.0.5" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> <script src="https://unpkg.com/idiomorph@0.7.3" integrity="sha384-JcorokHTL/m+D6ZHe2+yFVQopVwZ+91GxAPDyEZ6/A/OEPGEx1+MeNSe2OGvoRS9" crossorigin="anonymous"></script> <script src="https://unpkg.com/idiomorph@0.7.3/dist/idiomorph-ext.min.js" integrity="sha384-szktAZju9fwY15dZ6D2FKFN4eZoltuXiHStNDJWK9+FARrxJtquql828JzikODob" crossorigin="anonymous"></script> </head> diff --git a/www/content/extensions/preload.md b/www/content/extensions/preload.md index 9afa70e1..729d5a2f 100644 --- a/www/content/extensions/preload.md +++ b/www/content/extensions/preload.md @@ -15,15 +15,15 @@ unused requests. Use this extension carefully! The fastest way to install `preload` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> - <script src="https://unpkg.com/htmx-ext-preload@2.1.0" integrity="sha384-fkzubQiTB69M7XTToqW6tplvxAOJkqPl5JmLAbumV2EacmuJb8xEP9KnJafk/rg8" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx-ext-preload@2.1.0" integrity="sha384-fkzubQiTB69M7XTToqW6tplvxAOJkqPl5JmLAbumV2EacmuJb8xEP9KnJafk/rg8" crossorigin="anonymous"></script> </head> <body hx-ext="preload"> ... ``` -An unminified version is also available at https://unpkg.com/htmx-ext-preload/dist/preload.js. +An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-preload/dist/preload.js. -While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `preload` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-preload`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `preload` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-preload`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. For npm-style build systems, you can install `preload` via [npm](https://www.npmjs.com/): ```shell diff --git a/www/content/extensions/response-targets.md b/www/content/extensions/response-targets.md index 8b2ac954..60c3e975 100644 --- a/www/content/extensions/response-targets.md +++ b/www/content/extensions/response-targets.md @@ -27,15 +27,15 @@ The value of each attribute can be: The fastest way to install `response-targets` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> - <script src="https://unpkg.com/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx-ext-response-targets@2.0.2" integrity="sha384-T41oglUPvXLGBVyRdZsVRxNWnOOqCynaPubjUVjxhsjFTKrFJGEMm3/0KGmNQ+Pg" crossorigin="anonymous"></script> </head> <body hx-ext="response-targets"> ... ``` -An unminified version is also available at https://unpkg.com/htmx-ext-response-targets/dist/response-targets.js. +An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-response-targets/dist/response-targets.js. -While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `response-targets` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-response-targets`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `response-targets` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-response-targets`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. For npm-style build systems, you can install `response-targets` via [npm](https://www.npmjs.com/): ```shell diff --git a/www/content/extensions/sse.md b/www/content/extensions/sse.md index d9e469da..4da6118f 100644 --- a/www/content/extensions/sse.md +++ b/www/content/extensions/sse.md @@ -29,14 +29,14 @@ Use the following attributes to configure how SSE connections behave: The fastest way to install `sse` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> - <script src="https://unpkg.com/htmx-ext-sse@2.2.3" integrity="sha384-Y4gc0CK6Kg+hmulDc6rZPJu0tqvk7EWlih0Oh+2OkAi1ZDlCbBDCQEE2uVk472Ky" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx-ext-sse@2.2.2" integrity="sha384-Y4gc0CK6Kg+hmulDc6rZPJu0tqvk7EWlih0Oh+2OkAi1ZDlCbBDCQEE2uVk472Ky" crossorigin="anonymous"></script> </head> <body hx-ext="sse"> ``` -An unminified version is also available at https://unpkg.com/htmx-ext-sse/dist/sse.js. +An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-sse/dist/sse.js. -While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `sse` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-sse`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `sse` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-sse`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. For npm-style build systems, you can install `sse` via [npm](https://www.npmjs.com/): ```shell diff --git a/www/content/extensions/ws.md b/www/content/extensions/ws.md index 3e247783..e938c624 100644 --- a/www/content/extensions/ws.md +++ b/www/content/extensions/ws.md @@ -23,14 +23,14 @@ Use the following attributes to configure how WebSockets behave: The fastest way to install `ws` is to load it via a CDN. Remember to always include the core htmx library before the extension and [enable the extension](#usage). ```HTML <head> - <script src="https://unpkg.com/htmx.org@2.0.4" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> - <script src="https://unpkg.com/htmx-ext-ws@2.0.2" integrity="sha384-vuKxTKv5TX/b3lLzDKP2U363sOAoRo5wSvzzc3LJsbaQRSBSS+3rKKHcOx5J8doU" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.5/dist/htmx.min.js" integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+" crossorigin="anonymous"></script> + <script src="https://cdn.jsdelivr.net/npm/htmx-ext-ws@2.0.2" integrity="sha384-vuKxTKv5TX/b3lLzDKP2U363sOAoRo5wSvzzc3LJsbaQRSBSS+3rKKHcOx5J8doU" crossorigin="anonymous"></script> </head> <body hx-ext="ws"> ``` -An unminified version is also available at https://unpkg.com/htmx-ext-ws/dist/ws.js. +An unminified version is also available at https://cdn.jsdelivr.net/npm/htmx-ext-ws/dist/ws.js. -While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `ws` is to simply copy it into your project. Download the extension from `https://unpkg.com/htmx-ext-ws`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. +While the CDN approach is simple, you may want to consider [not using CDNs in production](https://blog.wesleyac.com/posts/why-not-javascript-cdn). The next easiest way to install `ws` is to simply copy it into your project. Download the extension from `https://cdn.jsdelivr.net/npm/htmx-ext-ws`, add it to the appropriate directory in your project and include it where necessary with a `<script>` tag. For npm-style build systems, you can install `ws` via [npm](https://www.npmjs.com/): ```shell diff --git a/www/content/reference.md b/www/content/reference.md index ebdb81c1..71a87983 100644 --- a/www/content/reference.md +++ b/www/content/reference.md @@ -146,8 +146,9 @@ All other attributes available in htmx. | [`htmx:configRequest`](@/events.md#htmx:configRequest) | triggered before the request, allows you to customize parameters, headers | [`htmx:confirm`](@/events.md#htmx:confirm) | triggered after a trigger occurs on an element, allows you to cancel (or delay) issuing the AJAX request | [`htmx:historyCacheError`](@/events.md#htmx:historyCacheError) | triggered on an error during cache writing +| [`htmx:historyCacheHit`](@/events.md#htmx:historyCacheHit) | triggered on a cache hit in the history subsystem | [`htmx:historyCacheMiss`](@/events.md#htmx:historyCacheMiss) | triggered on a cache miss in the history subsystem -| [`htmx:historyCacheMissError`](@/events.md#htmx:historyCacheMissError) | triggered on a unsuccessful remote retrieval +| [`htmx:historyCacheMissLoadError`](@/events.md#htmx:historyCacheMissLoadError) | triggered on a unsuccessful remote retrieval | [`htmx:historyCacheMissLoad`](@/events.md#htmx:historyCacheMissLoad) | triggered on a successful remote retrieval | [`htmx:historyRestore`](@/events.md#htmx:historyRestore) | triggered when htmx handles a history restoration action | [`htmx:beforeHistorySave`](@/events.md#htmx:beforeHistorySave) | triggered before content is saved to the history cache @@ -219,42 +220,44 @@ listed below: <div class="info-table"> -| Config Variable | Info | -|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `htmx.config.historyEnabled` | defaults to `true`, really only useful for testing | -| `htmx.config.historyCacheSize` | defaults to 10 | -| `htmx.config.refreshOnHistoryMiss` | defaults to `false`, if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request | -| `htmx.config.defaultSwapStyle` | defaults to `innerHTML` | -| `htmx.config.defaultSwapDelay` | defaults to 0 | -| `htmx.config.defaultSettleDelay` | defaults to 20 | -| `htmx.config.includeIndicatorStyles` | defaults to `true` (determines if the indicator styles are loaded) | -| `htmx.config.indicatorClass` | defaults to `htmx-indicator` | -| `htmx.config.requestClass` | defaults to `htmx-request` | -| `htmx.config.addedClass` | defaults to `htmx-added` | -| `htmx.config.settlingClass` | defaults to `htmx-settling` | -| `htmx.config.swappingClass` | defaults to `htmx-swapping` | -| `htmx.config.allowEval` | defaults to `true`, can be used to disable htmx's use of eval for certain features (e.g. trigger filters) | -| `htmx.config.allowScriptTags` | defaults to `true`, determines if htmx will process script tags found in new content | -| `htmx.config.inlineScriptNonce` | defaults to `''`, meaning that no nonce will be added to inline scripts | -| `htmx.config.inlineStyleNonce` | defaults to `''`, meaning that no nonce will be added to inline styles | -| `htmx.config.attributesToSettle` | defaults to `["class", "style", "width", "height"]`, the attributes to settle during the settling phase | -| `htmx.config.wsReconnectDelay` | defaults to `full-jitter` | -| `htmx.config.wsBinaryType` | defaults to `blob`, the [the type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection | -| `htmx.config.disableSelector` | defaults to `[hx-disable], [data-hx-disable]`, htmx will not process elements with this attribute on it or a parent | -| `htmx.config.disableInheritance` | defaults to `false`. If it is set to `true`, the inheritance of attributes is completely disabled and you can explicitly specify the inheritance with the [hx-inherit](@/attributes/hx-inherit.md) attribute. -| `htmx.config.withCredentials` | defaults to `false`, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates | -| `htmx.config.timeout` | defaults to 0, the number of milliseconds a request can take before automatically being terminated | -| `htmx.config.scrollBehavior` | defaults to 'instant', the scroll behavior when using the [show](@/attributes/hx-swap.md#scrolling-scroll-show) modifier with `hx-swap`. The allowed values are `instant` (scrolling should happen instantly in a single jump), `smooth` (scrolling should animate smoothly) and `auto` (scroll behavior is determined by the computed value of [scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)). | -| `htmx.config.defaultFocusScroll` | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier. | -| `htmx.config.getCacheBusterParam` | defaults to false, if set to true htmx will append the target element to the `GET` request in the format `org.htmx.cache-buster=targetElementId` | -| `htmx.config.globalViewTransitions` | if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content. | -| `htmx.config.methodsThatUseUrlParams` | defaults to `["get", "delete"]`, htmx will format requests with these methods by encoding their parameters in the URL, not the request body | -| `htmx.config.selfRequestsOnly` | defaults to `true`, whether to only allow AJAX requests to the same domain as the current document | -| `htmx.config.ignoreTitle` | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content | -| `htmx.config.scrollIntoViewOnBoost` | defaults to `true`, whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. | -| `htmx.config.triggerSpecsCache` | defaults to `null`, the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) | -| `htmx.config.responseHandling` | the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error | -| `htmx.config.allowNestedOobSwaps` | defaults to `true`, whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). | +| Config Variable | Info | +|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `htmx.config.historyEnabled` | defaults to `true`, really only useful for testing | +| `htmx.config.historyCacheSize` | defaults to 10 | +| `htmx.config.refreshOnHistoryMiss` | defaults to `false`, if set to `true` htmx will issue a full page refresh on history misses rather than use an AJAX request | +| `htmx.config.defaultSwapStyle` | defaults to `innerHTML` | +| `htmx.config.defaultSwapDelay` | defaults to 0 | +| `htmx.config.defaultSettleDelay` | defaults to 20 | +| `htmx.config.includeIndicatorStyles` | defaults to `true` (determines if the indicator styles are loaded) | +| `htmx.config.indicatorClass` | defaults to `htmx-indicator` | +| `htmx.config.requestClass` | defaults to `htmx-request` | +| `htmx.config.addedClass` | defaults to `htmx-added` | +| `htmx.config.settlingClass` | defaults to `htmx-settling` | +| `htmx.config.swappingClass` | defaults to `htmx-swapping` | +| `htmx.config.allowEval` | defaults to `true`, can be used to disable htmx's use of eval for certain features (e.g. trigger filters) | +| `htmx.config.allowScriptTags` | defaults to `true`, determines if htmx will process script tags found in new content | +| `htmx.config.inlineScriptNonce` | defaults to `''`, meaning that no nonce will be added to inline scripts | +| `htmx.config.inlineStyleNonce` | defaults to `''`, meaning that no nonce will be added to inline styles | +| `htmx.config.attributesToSettle` | defaults to `["class", "style", "width", "height"]`, the attributes to settle during the settling phase | +| `htmx.config.wsReconnectDelay` | defaults to `full-jitter` | +| `htmx.config.wsBinaryType` | defaults to `blob`, the [the type of binary data](https://developer.mozilla.org/docs/Web/API/WebSocket/binaryType) being received over the WebSocket connection | +| `htmx.config.disableSelector` | defaults to `[hx-disable], [data-hx-disable]`, htmx will not process elements with this attribute on it or a parent | +| `htmx.config.disableInheritance` | defaults to `false`. If it is set to `true`, the inheritance of attributes is completely disabled and you can explicitly specify the inheritance with the [hx-inherit](@/attributes/hx-inherit.md) attribute. +| `htmx.config.withCredentials` | defaults to `false`, allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates | +| `htmx.config.timeout` | defaults to 0, the number of milliseconds a request can take before automatically being terminated | +| `htmx.config.scrollBehavior` | defaults to 'instant', the scroll behavior when using the [show](@/attributes/hx-swap.md#scrolling-scroll-show) modifier with `hx-swap`. The allowed values are `instant` (scrolling should happen instantly in a single jump), `smooth` (scrolling should animate smoothly) and `auto` (scroll behavior is determined by the computed value of [scroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior)). | +| `htmx.config.defaultFocusScroll` | if the focused element should be scrolled into view, defaults to false and can be overridden using the [focus-scroll](@/attributes/hx-swap.md#focus-scroll) swap modifier. | +| `htmx.config.getCacheBusterParam` | defaults to false, if set to true htmx will append the target element to the `GET` request in the format `org.htmx.cache-buster=targetElementId` | +| `htmx.config.globalViewTransitions` | if set to `true`, htmx will use the [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) API when swapping in new content. | +| `htmx.config.methodsThatUseUrlParams` | defaults to `["get", "delete"]`, htmx will format requests with these methods by encoding their parameters in the URL, not the request body | +| `htmx.config.selfRequestsOnly` | defaults to `true`, whether to only allow AJAX requests to the same domain as the current document | +| `htmx.config.ignoreTitle` | defaults to `false`, if set to `true` htmx will not update the title of the document when a `title` tag is found in new content | +| `htmx.config.scrollIntoViewOnBoost` | defaults to `true`, whether or not the target of a boosted element is scrolled into the viewport. If `hx-target` is omitted on a boosted element, the target defaults to `body`, causing the page to scroll to the top. | +| `htmx.config.triggerSpecsCache` | defaults to `null`, the cache to store evaluated trigger specifications into, improving parsing performance at the cost of more memory usage. You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) | +| `htmx.config.responseHandling` | the default [Response Handling](@/docs.md#response-handling) behavior for response status codes can be configured here to either swap or error | +| `htmx.config.allowNestedOobSwaps` | defaults to `true`, whether to process OOB swaps on elements that are nested within the main response element. See [Nested OOB Swaps](@/attributes/hx-swap-oob.md#nested-oob-swaps). | +| `htmx.config.historyRestoreAsHxRequest`| defaults to `true`, Whether to treat history cache miss full page reload requests as a "HX-Request" by returning this response header. This should always be disabled when using HX-Request header to optionally return partial responses | + </div> |