From 5b2fe2c19c3eeee1ac14dbf5c44099af04dbcc79 Mon Sep 17 00:00:00 2001 From: Carson Gross Date: Thu, 3 Oct 2024 18:52:59 -0600 Subject: [PATCH] move general extension docs back to htmx.org/extensions and include core extension documentation on the site --- CHANGELOG.md | 1 + README.md | 2 +- dist/ext/README.md | 2 +- dist/ext/ajax-header.js | 2 +- dist/ext/alpine-morph.js | 2 +- dist/ext/class-tools.js | 2 +- dist/ext/client-side-templates.js | 2 +- dist/ext/debug.js | 2 +- dist/ext/disable-element.js | 2 +- dist/ext/event-header.js | 2 +- dist/ext/head-support.js | 2 +- dist/ext/include-vals.js | 2 +- dist/ext/json-enc.js | 2 +- dist/ext/loading-states.js | 2 +- dist/ext/method-override.js | 2 +- dist/ext/morphdom-swap.js | 2 +- dist/ext/multi-swap.js | 2 +- dist/ext/path-deps.js | 2 +- dist/ext/path-params.js | 2 +- dist/ext/preload.js | 2 +- dist/ext/rails-method.js | 2 +- dist/ext/remove-me.js | 2 +- dist/ext/response-targets.js | 2 +- dist/ext/restored.js | 2 +- dist/ext/sse.js | 2 +- dist/ext/ws.js | 2 +- www/content/_index.md | 2 +- www/content/api.md | 4 +- www/content/attributes/hx-ext.md | 2 +- www/content/docs.md | 50 +++- www/content/extensions/_index.md | 51 +++- www/content/extensions/building.md | 31 +++ www/content/extensions/head-support.md | 113 +++++++++ www/content/extensions/htmx-1-compat.md | 41 ++++ www/content/extensions/idiomorph.md | 44 ++++ www/content/extensions/preload.md | 139 +++++++++++ www/content/extensions/response-targets.md | 142 ++++++++++++ www/content/extensions/sse.md | 234 +++++++++++++++++++ www/content/extensions/ws.md | 256 +++++++++++++++++++++ www/content/migration-guide-htmx-1.md | 4 +- www/content/migration-guide-intercooler.md | 2 +- www/content/reference.md | 6 +- www/themes/htmx-theme/templates/page.html | 4 +- 43 files changed, 1125 insertions(+), 51 deletions(-) create mode 100644 www/content/extensions/building.md create mode 100644 www/content/extensions/head-support.md create mode 100644 www/content/extensions/htmx-1-compat.md create mode 100644 www/content/extensions/idiomorph.md create mode 100644 www/content/extensions/preload.md create mode 100644 www/content/extensions/response-targets.md create mode 100644 www/content/extensions/sse.md create mode 100644 www/content/extensions/ws.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8328da4c..8bd5fd43 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ * Better degredation of `hx-boost` on forms with query parameters in their `action` * Improved shadowRoot support * Many smaller bug fixes +* Moved the core extension documentation back to ## [2.0.2] - 2024-08-12 * no longer boost forms of type `dialog` diff --git a/README.md b/README.md index cb6b74f2..01d4604f 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ directly in HTML, using [attributes](https://htmx.org/reference#attributes), so htmx is small ([~14k min.gz'd](https://unpkg.com/htmx.org/dist/)), [dependency-free](https://github.com/bigskysoftware/htmx/blob/master/package.json) & -[extendable](https://extensions.htmx.org/) +[extendable](https://htmx.org/extensions) ## motivation diff --git a/dist/ext/README.md b/dist/ext/README.md index 1904ec05..366e714e 100644 --- a/dist/ext/README.md +++ b/dist/ext/README.md @@ -4,6 +4,6 @@ These are legacy extensions for htmx 1.x and are **NOT** actively maintained or They are here because we unfortunately linked to unversioned unpkg URLs in the installation guides for them in 1.x, so we need to keep them here to preserve those URLs and not break existing users functionality. -If you are looking for extensions for htmx 2.x, please see the [htmx 2.0 extensions site](https://extensions.htmx.org), +If you are looking for extensions for htmx 2.x, please see the [htmx 2.0 extensions site](https://htmx.org/extensions), which has links to the new extensions repos (They have all been moved to their own NPM projects and URLs, like they should have been from the start!) diff --git a/dist/ext/ajax-header.js b/dist/ext/ajax-header.js index be4758d5..e8c2dbcc 100644 --- a/dist/ext/ajax-header.js +++ b/dist/ext/ajax-header.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('ajax-header', { onEvent: function (name, evt) { diff --git a/dist/ext/alpine-morph.js b/dist/ext/alpine-morph.js index fcf4b2b4..ea41cf08 100644 --- a/dist/ext/alpine-morph.js +++ b/dist/ext/alpine-morph.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('alpine-morph', { isInlineSwap: function (swapStyle) { diff --git a/dist/ext/class-tools.js b/dist/ext/class-tools.js index 7d4bfa87..83f5c7c5 100644 --- a/dist/ext/class-tools.js +++ b/dist/ext/class-tools.js @@ -2,7 +2,7 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } function splitOnWhitespace(trigger) { diff --git a/dist/ext/client-side-templates.js b/dist/ext/client-side-templates.js index a8e24ddf..d23c5c9f 100644 --- a/dist/ext/client-side-templates.js +++ b/dist/ext/client-side-templates.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('client-side-templates', { transformResponse : function(text, xhr, elt) { diff --git a/dist/ext/debug.js b/dist/ext/debug.js index b8a59a17..aa88c9e4 100644 --- a/dist/ext/debug.js +++ b/dist/ext/debug.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('debug', { onEvent: function (name, evt) { diff --git a/dist/ext/disable-element.js b/dist/ext/disable-element.js index b9e25935..0192661f 100644 --- a/dist/ext/disable-element.js +++ b/dist/ext/disable-element.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } // Disable Submit Button htmx.defineExtension('disable-element', { diff --git a/dist/ext/event-header.js b/dist/ext/event-header.js index bcc5567c..0ccb7de3 100644 --- a/dist/ext/event-header.js +++ b/dist/ext/event-header.js @@ -1,7 +1,7 @@ (function(){ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } function stringifyEvent(event) { var obj = {}; diff --git a/dist/ext/head-support.js b/dist/ext/head-support.js index 906ca233..07c0231d 100644 --- a/dist/ext/head-support.js +++ b/dist/ext/head-support.js @@ -7,7 +7,7 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } var api = null; diff --git a/dist/ext/include-vals.js b/dist/ext/include-vals.js index 52ec67fb..53332d39 100644 --- a/dist/ext/include-vals.js +++ b/dist/ext/include-vals.js @@ -1,7 +1,7 @@ (function(){ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } function mergeObjects(obj1, obj2) { diff --git a/dist/ext/json-enc.js b/dist/ext/json-enc.js index 02b1792f..ef056801 100644 --- a/dist/ext/json-enc.js +++ b/dist/ext/json-enc.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('json-enc', { onEvent: function (name, evt) { diff --git a/dist/ext/loading-states.js b/dist/ext/loading-states.js index b5dfcf0e..17743047 100644 --- a/dist/ext/loading-states.js +++ b/dist/ext/loading-states.js @@ -2,7 +2,7 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } let loadingStatesUndoQueue = [] diff --git a/dist/ext/method-override.js b/dist/ext/method-override.js index cd84d6e5..44621cdc 100644 --- a/dist/ext/method-override.js +++ b/dist/ext/method-override.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('method-override', { onEvent: function (name, evt) { diff --git a/dist/ext/morphdom-swap.js b/dist/ext/morphdom-swap.js index 13d58adf..337a6040 100644 --- a/dist/ext/morphdom-swap.js +++ b/dist/ext/morphdom-swap.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('morphdom-swap', { isInlineSwap: function(swapStyle) { diff --git a/dist/ext/multi-swap.js b/dist/ext/multi-swap.js index a9435323..0c882f83 100644 --- a/dist/ext/multi-swap.js +++ b/dist/ext/multi-swap.js @@ -2,7 +2,7 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } /** @type {import("../htmx").HtmxInternalApi} */ diff --git a/dist/ext/path-deps.js b/dist/ext/path-deps.js index 19e8541c..8460e838 100644 --- a/dist/ext/path-deps.js +++ b/dist/ext/path-deps.js @@ -2,7 +2,7 @@ 'use strict'; if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } // Save a reference to the global object (window in the browser) var _root = this; diff --git a/dist/ext/path-params.js b/dist/ext/path-params.js index 173696e0..462be0a3 100644 --- a/dist/ext/path-params.js +++ b/dist/ext/path-params.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('path-params', { onEvent: function(name, evt) { diff --git a/dist/ext/preload.js b/dist/ext/preload.js index 74c5a3f7..ac3ef5c9 100644 --- a/dist/ext/preload.js +++ b/dist/ext/preload.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } // This adds the "preload" extension to htmx. By default, this will // preload the targets of any tags with `href` or `hx-get` attributes diff --git a/dist/ext/rails-method.js b/dist/ext/rails-method.js index 4843a346..632d86cd 100644 --- a/dist/ext/rails-method.js +++ b/dist/ext/rails-method.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('rails-method', { onEvent: function (name, evt) { diff --git a/dist/ext/remove-me.js b/dist/ext/remove-me.js index 47faf736..21cd7880 100644 --- a/dist/ext/remove-me.js +++ b/dist/ext/remove-me.js @@ -1,7 +1,7 @@ (function(){ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } function maybeRemoveMe(elt) { var timing = elt.getAttribute("remove-me") || elt.getAttribute("data-remove-me"); diff --git a/dist/ext/response-targets.js b/dist/ext/response-targets.js index a23c1aed..021ec0dc 100644 --- a/dist/ext/response-targets.js +++ b/dist/ext/response-targets.js @@ -2,7 +2,7 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } /** @type {import("../htmx").HtmxInternalApi} */ diff --git a/dist/ext/restored.js b/dist/ext/restored.js index 13daa343..a314b074 100644 --- a/dist/ext/restored.js +++ b/dist/ext/restored.js @@ -1,6 +1,6 @@ if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } htmx.defineExtension('restored', { onEvent : function(name, evt) { diff --git a/dist/ext/sse.js b/dist/ext/sse.js index 5fecef65..16eee54e 100644 --- a/dist/ext/sse.js +++ b/dist/ext/sse.js @@ -9,7 +9,7 @@ This extension adds support for Server Sent Events to htmx. See /www/extensions if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } /** @type {import("../htmx").HtmxInternalApi} */ diff --git a/dist/ext/ws.js b/dist/ext/ws.js index 8488b18b..3d7e44db 100644 --- a/dist/ext/ws.js +++ b/dist/ext/ws.js @@ -8,7 +8,7 @@ This extension adds support for WebSockets to htmx. See /www/extensions/ws.md f if (htmx.version && !htmx.version.startsWith("1.")) { console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version + - ". It is recommended that you move to the version of this extension found on https://extensions.htmx.org") + ". It is recommended that you move to the version of this extension found on https://htmx.org/extensions") } /** @type {import("../htmx").HtmxInternalApi} */ diff --git a/www/content/_index.md b/www/content/_index.md index e9f718eb..828c9e97 100644 --- a/www/content/_index.md +++ b/www/content/_index.md @@ -105,7 +105,7 @@ directly in HTML, using [attributes](@/reference.md#attributes), so you can buil htmx is small ([~14k min.gz'd](https://unpkg.com/htmx.org/dist/)), [dependency-free](https://github.com/bigskysoftware/htmx/blob/master/package.json), -[extendable](https://extensions.htmx.org) & has **reduced** code base sizes by [67% when compared with react](@/essays/a-real-world-react-to-htmx-port.md) +[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)

motivation

diff --git a/www/content/api.md b/www/content/api.md index 783ea9c8..e2dada72 100644 --- a/www/content/api.md +++ b/www/content/api.md @@ -2,7 +2,7 @@ title = "Javascript API" +++ -While it is not a focus of the library, htmx does provide a small API of helper methods, intended mainly for [extension development](https://extensions.htmx.org) or for working with [events](@/events.md). +While it is not a focus of the library, htmx does provide a small API of helper methods, intended mainly for [extension development](https://htmx.org/extensions) or for working with [events](@/events.md). The [hyperscript](https://hyperscript.org) project is intended to provide more extensive scripting support for htmx-based applications. @@ -183,7 +183,7 @@ to provide custom WebSocket setup. ### Method - `htmx.defineExtension()` {#defineExtension} -Defines a new htmx [extension](https://extensions.htmx.org). +Defines a new htmx [extension](https://htmx.org/extensions). ##### Parameters diff --git a/www/content/attributes/hx-ext.md b/www/content/attributes/hx-ext.md index 03b995f4..65dcbb6b 100644 --- a/www/content/attributes/hx-ext.md +++ b/www/content/attributes/hx-ext.md @@ -2,7 +2,7 @@ title = "hx-ext" +++ -The `hx-ext` attribute enables an htmx [extension](https://extensions.htmx.org) for an element and all its children. +The `hx-ext` attribute enables an htmx [extension](https://htmx.org/extensions) for an element and all its children. The value can be a single extension name or a comma separated list of extensions to apply. diff --git a/www/content/docs.md b/www/content/docs.md index 922fdda4..a39979ac 100644 --- a/www/content/docs.md +++ b/www/content/docs.md @@ -448,7 +448,7 @@ cost of more CPU. The following extensions are available for morph-style swaps: -* [Idiomorph](https://github.com/bigskysoftware/idiomorph#htmx) - A morphing algorithm created by the htmx developers. +* [Idiomorph](/extensions/idiomorph) - A morphing algorithm created by the htmx developers. * [Morphdom Swap](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/morphdom-swap/README.md) - Based on the [morphdom](https://github.com/patrick-steele-idem/morphdom), the original DOM morphing library. * [Alpine-morph](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/alpine-morph/README.md) - Based on the [alpine morph](https://alpinejs.dev/plugins/morph) plugin, plays @@ -841,7 +841,7 @@ As such, the normal HTML accessibility recommendations apply. For example: ## Web Sockets & SSE {#websockets-and-sse} Web Sockets and Server Sent Events (SSE) are supported via extensions. Please see -the [SSE extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/sse/README.md) and [WebSocket extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/ws/README.md) +the [SSE extension](/extensions/sse) and [WebSocket extension](/extensions/ws) pages to learn more. ## History Support {#history} @@ -999,7 +999,7 @@ If you wanted to swap everything, regardless of HTTP response code, you could us ``` -Finally, it is worth considering using the [Response Targets](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/response-targets/README.md) +Finally, it is worth considering using the [Response Targets](/extensions/reponse-targets) extension, which allows you to configure the behavior of response codes declaratively via attributes. ### CORS @@ -1117,20 +1117,46 @@ Please see the [Animation Guide](@/examples/animations.md) for more details on t ## Extensions -Htmx has an extension mechanism that allows you to customize the libraries' behavior. -Extensions [are defined in javascript](https://github.com/bigskysoftware/htmx-extensions/tree/main?tab=readme-ov-file#defining-an-extension) and then used via -the [`hx-ext`](@/attributes/hx-ext.md) attribute: +htmx provides an [extensions](/extensions) mechanism that allows you to customize the libraries' behavior. +Extensions [are defined in javascript](/extensions/building) and then enabled via +the [`hx-ext`](@/attributes/hx-ext.md) attribute. + +Here is how you would install the [idiomorph](@extension/idiomorph) extension, which allows you to use the +[Idiomorph](https://github.com/bigskysoftware/idiomorph) DOM morphing algorithms for htmx swaps: ```html -
- - -
+ + + + + ... + + ... + ``` -For existing extensions, please [see the extensions site](https://extensions.htmx.org). +First the extension is included (it should be included *after* `htmx.js` is included), then the extension is referenced +by name via the `hx-ext` attribute. This enables you to then use the `morph` swap. -If you are interested in adding your own extension to htmx, please [see the extension docs](https://github.com/bigskysoftware/htmx-extensions/tree/main?tab=readme-ov-file#defining-an-extension). +### Core Extensions + +htmx supports a few "core" extensions, which are supported by the htmx development team: + +* [head-support](/extensions/head-support) - support for merging head tag information (styles, etc.) in htmx requests | +* [htmx-1-compat](/extensions/htmx-1-compat) - restores htmx 1 defaults & functionality +* [idiomorph](/extensions/idiomorph) - supports the `morph` swap strategy using idiomorph +* [preload](/extensions/preload) - allows you to preload content for better performance +* [response-targets](/extensions/response-targets) - allows you to target elements based on HTTP response codes (e.g. `404`) +* [sse](/extensions/sse) - support for [Serve Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) +* [ws](/extensions/ws) - support for [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) + +You can see all available extensions on the [Extensions](/extensions) page. + +### Creating Extensions + +If you are interested in adding your own extension to htmx, please [see the extension docs](/extensions/building). ## Events & Logging {#events} diff --git a/www/content/extensions/_index.md b/www/content/extensions/_index.md index 24b3d9e6..84803b68 100644 --- a/www/content/extensions/_index.md +++ b/www/content/extensions/_index.md @@ -1,3 +1,52 @@ +++ -redirect_to = "https://extensions.htmx.org" +title = "Extensions" +++ + +htmx supports extensions to augment the core hypermedia infrastructure it provides. The extension mechanism takes +pressure off the core library to add new features, allowing it to focus on its main purpose of +[generalizing hypermedia controls](https://dl.acm.org/doi/10.1145/3648188.3675127). + +If you are interested in creating an extension for htmx, please see [Building htmx Extensions](/extensions/building). + +htmx extensions are split into two categories: + +* [core extensions](#core-extensions) - supported by the htmx team +* [community extensions](#community-extensions) - supported by the broader community + +## Core Extensions + +| Name | Description | +|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [head-support](/extensions/head-support) | Provides support for merging head tag information (styles, etc.) in htmx requests | +| [htmx-1-compat](/extensions/htmx-1-compat) | Rolls back most of the behavioral changes of htmx 2 to the htmx 1 defaults. | +| [idiomorph](/extensions/idiomorph) | Provides a `morph` swap strategy based on the [idiomorph](https://github.com/bigskysoftware/idiomorph/) morphing library, which was created by the htmx team. | +| [preload](/extensions/preload) | This extension allows you to load HTML fragments into your browser's cache before they are requested by the user, so that additional pages appear to users to load nearly instantaneously. | +| [response-targets](/extensions/response-targets) | This extension allows you to specify different target elements to be swapped when different HTTP response codes are received. | +| [sse](/extensions/sse) | Provides support for [Serve Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) directly from HTML. | +| [ws](/extensions/ws) | Provides bi-directional communication with [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) servers directly from HTML | + +## Community Extensions + +| Name | Description | +|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [ajax-header](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/ajax-header/README.md) | Adds an `X-Requested-With` header to all requests made by htmx | +| [alpine-morph](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/alpine-morph/README.md) | Alpine.js now has a lightweight [morph plugin](https://alpinejs.dev/plugins/morph) and this extension allows you to use it as the swapping mechanism in htmx which is necessary to retain Alpine state when you have entire Alpine components swapped by htmx. | +| [class-tools](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/class-tools/README.md) | The `class-tools` extension allows you to specify CSS classes that will be swapped onto or off of the elements by using a `classes` or `data-classes` attribute. | +| [client-side-templates](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/client-side-templates/README.md) | This extension supports transforming a JSON/XML request response into HTML via a client-side template before it is swapped into the DOM. | +| [debug](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/debug/README.md) | This extension includes log all htmx events for the element it is on, either through the `console.debug` function or through the `console.log` function with a `DEBUG:` prefix. | +| [disable-element](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/disable-element/README.md) | This extension disables an element during an htmx request, when configured on the element triggering the request. Note that this functionality is now part of the core of htmx via the `hx-disabled-elt` attribute | +| [event-header](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/event-header/README.md) | This extension adds the `Triggering-Event` header to requests. The value of the header is a JSON serialized version of the event that triggered the request. | +| [include-vals](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/include-vals/README.md) | The `include-vals` extension allows you to programmatically include values in a request with a `include-vals` attribute. The value of this attribute is one or more name/value pairs, which will be evaluated as the fields in a javascript object literal. | +| [json-enc-custom](https://github.com/Emtyloc/json-enc-custom/blob/main/README.md) | This extension works similarly to json-enc but allows for very complex structures, such as embedding JSON objects, lists, or handling indexes, just by using the name attribute. | +| [json-enc](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/json-enc/README.md) | This extension encodes parameters in JSON format instead of url format. | +| [loading-states](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/loading-states/README.md) | This extension allows you to easily manage loading states while a request is in flight, including disabling elements, and adding and removing CSS classes. | +| [morphdom-swap](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/morphdom-swap/README.md) | Provides a `morph` swap strategy based on the [morphdom](https://github.com/patrick-steele-idem/morphdom/) morphing library. | +| [multi-swap](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/multi-swap/README.md) | This extension allows you to swap multiple elements marked from the HTML response. You can also choose for each element which swap method should be used. | +| [no-cache](https://github.com/craigharman/htmx-ext-no-cache/README.md) | This extension forces HTMX to bypass client caches and make a new request. An `hx-no-cache` header is also added to allow server-side caching to be bypassed. | +| [path-deps](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md) | This extension supports expressing inter-element dependencies based on paths, inspired by the [intercooler.js dependencies mechanism](http://intercoolerjs.org/docs.html#dependencies). | +| [path-params](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-params/README.md) | This extension uses request parameters to populate path variables. Used parameters are removed so they won't be sent in the query string or body anymore. | +| [remove-me](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/remove-me/README.md) | Allows you to remove an element after a specified interval. | +| [replace-params](https://github.com/fanelfaa/htmx-ext-replace-params/blob/main/README.md) | This extension uses request parameters to replace existing parameters. If given value is empty string then parameter will be deleted. This extension would be useful in situations like pagination, search that you only want to replace only few parameters instead of reset all parameters. | +| [restored](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/restored/README.md) | Triggers an event whenever a back button even is detected while using `hx-boost` | +| [safe-nonce](https://github.com/MichaelWest22/htmx-extensions/blob/main/src/safe-nonce/README.md) | The `safe-nonce` extension can be used to improve the security of the application/web-site and help avoid XSS issues by allowing you to return known trusted inline scripts safely | +| [signalr](https://github.com/Renerick/htmx-signalr/blob/master/README.md) | Provides bidirectional real-time communication via [SignalR](https://github.com/dotnet/AspNetCore/tree/main/src/SignalR). | diff --git a/www/content/extensions/building.md b/www/content/extensions/building.md new file mode 100644 index 00000000..ffe47fe3 --- /dev/null +++ b/www/content/extensions/building.md @@ -0,0 +1,31 @@ ++++ +title = "Building htmx Extensions" ++++ + +To define an extension you call the `htmx.defineExtension()` function: + +```html + +``` + +Typically, this is done in a stand-alone javascript file, rather than in an inline `script` tag. + +Extensions should have names that are dash separated and that are reasonably short and descriptive. + +Extensions can override the following default extension points to add or change functionality: + +```javascript +{ + onEvent : function(name, evt) {return true;}, + transformResponse : function(text, xhr, elt) {return text;}, + isInlineSwap : function(swapStyle) {return false;}, + handleSwap : function(swapStyle, target, fragment, settleInfo) {return false;}, + encodeParameters : function(xhr, parameters, elt) {return null;} +} +``` diff --git a/www/content/extensions/head-support.md b/www/content/extensions/head-support.md new file mode 100644 index 00000000..dd034de7 --- /dev/null +++ b/www/content/extensions/head-support.md @@ -0,0 +1,113 @@ ++++ +title = "htmx Head Tag Support Extension" ++++ + +The `head-support` extension adds support for [head tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) +in responses to htmx requests. + +htmx began as a library focused on _partial replacement_ of HTML within the `body` tag. As such, merging additional +information such as the head tag was not a focus of the library. (This is in contrast with, for example, TurboLinks, +which was focused on merging entire web pages retrieved via AJAX into the browser.) + +The [`hx-boost`](@/attributes/hx-boost.md) attribute moved htmx closer to this world of full HTML-document support & +support for extracting the `title` tag out of head elements was eventually added, but full head tag support has never been +a feature of the library. This extension addresses that shortcoming. + +## Install + +```html + +``` + +## Usage + +```html + +... + +``` + +With this installed, all responses that htmx receives that contain a `head` tag in them (even if they are not complete +HTML documents with a root `` element) will be processed. + +How the head tag is handled depends on the type of htmx request. + +If the htmx request is from a boosted element, then the following merge algorithm is used: + +* Elements that exist in the current head as exact textual matches will be left in place +* Elements that do not exist in the current head will be added at the end of the head tag +* Elements that exist in the current head, but not in the new head will be removed from the head + +If the htmx request is from a non-boosted element, then all content will be _appended_ to the existing head element. + +If you wish to override this behavior in either case, you can place the `hx-head` attribute on the new `` tag, +with either of the following two values: + +* `merge` - follow the merging algorithm outlined above +* `append` - append the elements to the existing head + +### Controlling Merge Behavior + +Beyond this, you may also control merging behavior of individual elements with the following attributes: + +* If you place `hx-head="re-eval"` on a head element, it will be re-added (removed and appended) to the head tag on every +request, even if it already exists. This can be useful to execute a script on every htmx request, for example. +* If you place `hx-preserve="true"` on an element, it will never be removed from the head + +### Example + +As an example, consider the following head tag in an existing document: + +```html + + + + + + +``` + +If htmx receives a request containing this new head tag: + +```html + + + + + + +``` + +Then the following operations will occur: + +* `` will be left alone +* `` will be removed from the head +* `` will be added to the head +* `` will be removed from the head +* `` will be left alone +* `` will be added to the head + +The final head element will look like this: + +```html + + + + + + +``` + +## Events + +This extension triggers the following events: + +* `htmx:removingHeadElement` - triggered when a head element is about to be removed, with the element being removed +available in `event.detail.headElement`. If `preventDefault()` is invoked on the event, the element will not be removed. +* `htmx:addingHeadElement` - triggered when a head element is about to be added, with the element being added +available in `event.detail.headElement`. If `preventDefault()` is invoked on the event, the element will not be added. +* `htmx:afterHeadMerge` - triggered after a head tag merge has occurred, with the following values available in the event `detail`: +* `added` - added head elements +* `kept` - kept head elements +* `removed` - removed head elements +* `htmx:beforeHeadMerge` - triggered before a head merge occurs diff --git a/www/content/extensions/htmx-1-compat.md b/www/content/extensions/htmx-1-compat.md new file mode 100644 index 00000000..8f913c69 --- /dev/null +++ b/www/content/extensions/htmx-1-compat.md @@ -0,0 +1,41 @@ ++++ +title = "htmx 1.x Compatability Extension" ++++ + +The `htmx-1-compat` extension allows you to almost seamlessly upgrade from htmx 1.x to htmx 2. + +## Install + +```html + + +``` + +## What it covers + +Htmx 2 introduced a few [breaking changes](https://v2-0v2-0.htmx.org/migration-guide-htmx-1/). + +To make upgrading from htmx 1.x to htmx 2 easier, we're providing this extension that reverts most of those, so you're +able to benefit from the other changes without breaking your application. + +### Obsolete attributes + +- htmx 2 removed the deprecated [hx-ws](https://htmx.org/attributes/hx-ws/) + and [hx-sse](https://htmx.org/attributes/hx-sse/) attributes, that this extension restores. +- htmx 2 removed the deprecated `hx-on` attribute in favor of the + wildcard [`hx-on*` attribute](https://htmx.org/attributes/hx-on/), that this extension restores. + +### Default Changes + +- reverts [htmx.config.scrollBehavior](https://htmx.org/reference/#config) to 'smooth'. +- makes `DELETE` requests use a form-encoded body rather than URL parameters (htmx 2 uses URL parameters for `DELETE` as + default as per [the spec](https://www.rfc-editor.org/rfc/rfc9110.html#name-delete)). +- allows cross-domain requests by default (htmx 2 now forbids it by default). + +## What it does not cover + +- IE11 support was dropped in htmx 2, and this extension cannot revert that. If you need IE11 support, please stay with + htmx 1 that will continue being supported. +- htmx 2 introduced the breaking change that is the [swap method](https://v2-0v2-0.htmx.org/api/#swap) to the extensions + API. If you were only using core extensions, then you shouldn't need any additional work. If you were using custom or + community extensions, make sure that they were updated to work with htmx 2's API. diff --git a/www/content/extensions/idiomorph.md b/www/content/extensions/idiomorph.md new file mode 100644 index 00000000..aaf4db74 --- /dev/null +++ b/www/content/extensions/idiomorph.md @@ -0,0 +1,44 @@ ++++ +title = "htmx Idiomorph Extension" ++++ + +[Idiomorph](https://github.com/bigskysoftware/idiomorph) is a DOM morphing algorithm created by the htmx creator. DOM +morphing is a process where an existing DOM tree is "morphed" into the shape of another in a way that resuses as much of +the existing DOM's nodes as possible. By preserving nodes when changing from one tree to another you can present a +much smoother transition between the two states. + +You can use the idiomorph morphing algorith as a [swapping](@attributes/hx-swap) strategy by including the idiomorph +extension. + +## Install + +```html + +``` + +## Usage + +Once you have referenced the idiomorph extension, you can register it with the name `morph` on the body and then being +using `morph`, `morph:outerHTML` or `morph:innerHTML` as swap strategies. + +* `morph` & `morph:outerHTML` will morph the target element as well as it's children +* `morph:innerHTML` will morph only the inner children of an element, leaving the target untouched + +```html + + + + + + + + + +``` + diff --git a/www/content/extensions/preload.md b/www/content/extensions/preload.md new file mode 100644 index 00000000..ed26f726 --- /dev/null +++ b/www/content/extensions/preload.md @@ -0,0 +1,139 @@ ++++ +title = "htmx Preload Extension" ++++ + +The `preload` extension allows you to load HTML fragments into your browser's cache before they are requested by the +user, so that additional pages appear to users to load nearly instantaneously. As a developer, you can customize its +behavior to fit your applications needs and use cases. + +**IMPORTANT:** Preloading content judiciously can improve your web application's perceived performance, but preloading +too many resources can negatively impact your visitors' bandwidth and your server performance by initiating too many +unused requests. Use this extension carefully! + +## Install + +```html + +``` + +## Usage + +Register the extension with htmx using the `hx-ext` attribute. Then, add a `preload` attribute to any hyperlinks +and `hx-get` elements you want to preload. By default, resources will be loaded as soon as the `mousedown` event begins, +giving your application a roughly 100-200ms head start on serving responses. See configuration below for other options. + +```html + + +

What Works

+ WILL BE requested using a standard XMLHttpRequest() and default options (below) + + +

What WILL NOT WORK

+ WILL NOT be preloaded because it does not have an explicit "preload" attribute + WILL NOT be preloaded because it is an HX-POST transaction. + +``` + +### Inheriting Preload Settings + +You can add the `preload` attribute to the top-level element that contains several `` or `hx-get=""` +elements, and all of them will be preloaded. Be careful with this setting, because you can end up wasting bandwidth if +you preload many more resources than you need. + +```html + + + + +``` + +### Preloading of Linked Images + +After an HTML page (or page fragment) is preloaded, this extension can also preload linked image resources. It will not +load or run linked Javascript or Cascading Stylesheet content, whether linked or embedded in the preloaded HTML. To +preload images as well, use the following syntax. + +```html + +
+ Next Page +
+``` + +### Configuration + +Defaults for this extension are chosen to balance users' perceived performance with potential load on your servers from +unused requests. As a developer, you can modify two settings to customize this behavior to your specific use cases. + +#### preload="mousedown" (DEFAULT) + +The default behavior for this extension is to begin loading a resource when the user presses the mouse down. This is a +conservative setting that guarantees the user actually intends to use the linked resource. Because user click events +typically take 100-200ms to complete, this setting gives your server a significant headstart compared with a regular +click. + +```html +This will be preloaded when the user begins to click. +``` + +#### preload="mouseover" + +To preload links more aggressively, you can trigger the preload to happen when the user's mouse hovers over the link +instead. To prevent many resources from being loaded when the user scrolls or moves the mouse across a large list of +objects, a 100ms delay is built in to this action. If the user's mouse leaves the element *before* this timeout expires, +then the resource is not preloaded. + +Typical users hover over links for several hundred milliseconds before they click, which gives your server even more +time to respond to the request than the `mousedown` option +above. [Test your own hover timing here.](http://instantclick.io/click-test). However, be careful when using this +option because it can increase server load by requesting resources unnecessarily. + +```html +This will be preloaded when the user's mouse remains over it for more than + 100ms. +``` + +#### preload="custom-event-name" + +Preload can also listen to any custom event within the system, triggering resources to be preloaded (if they have not +already been cached by the browser). The extension itself generates an event called `preload:init` that can be used to +trigger preloads as soon as an object has been processed by htmx. + +```html + + + +
+
+ +``` + +* The response from the `/register` URL will replace contents of the `div` with the +`id` `response-div` when response code is 200 (OK). + +* The response from the `/register` URL will replace contents of the `div` with the `id` +`serious-errors` when response code begins with a digit 5 (server errors). + +* The response from the `/register` URL will replace contents of the `div` with +the `id` `not-found` when response code is 404 (Not Found). + +Sometimes you may not want to handle 5xx and 4xx errors separately, in which case you +can use `hx-target-error`: + +```html +
+
+ +
+
+``` + +2xx codes will be handled as in the previous example. However, when the response code is 5xx +or 4xx, the response from `/register` will replace the contents of the `div` with the `id` +`any-errors`. + +## Wildcard resolution + +When status response code does not match existing `hx-target-[CODE]` attribute name +then its numeric part expressed as a string is trimmed with last character being +replaced with the asterisk (`*`). This lookup process continues until the attribute +is found or there are no more digits. + +For example, if a browser receives 404 error code, the following attribute names will +be looked up (in the given order): + +* `hx-target-404` +* `hx-target-40*` +* `hx-target-4*` +* `hx-target-*`. + + +_If you are using tools that do not support asterisks in HTML attributes, you +may instead use the `x` character, e.g., `hx-target-4xx`._ + +## Notes + +* `hx-target-…` is inherited and can be placed on a parent element. +* `hx-target-…` cannot be used to handle HTTP response code 200. +* `hx-target-…` will honor `HX-Retarget` by default and will prefer it over any +calculated target but it can be changed by disabling the +`htmx.config.responseTargetPrefersRetargetHeader` configuration option. +* To avoid surprises the `hx-ext` attribute used to enable this extension should be +placed on a parent element containing elements with `hx-target-…` and `hx-target` +attributes. + +## See also + +* [`hx-target`](https://htmx.org/reference/hx-target.md), specifies the target element to be swapped diff --git a/www/content/extensions/sse.md b/www/content/extensions/sse.md new file mode 100644 index 00000000..4df03528 --- /dev/null +++ b/www/content/extensions/sse.md @@ -0,0 +1,234 @@ ++++ +title = "htmx Server Sent Event (SSE) Extension" ++++ + +The `Server Sent Events` extension connects to +an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) directly +from HTML. It manages the connections to your web server, listens for server events, and then swaps their contents into +your htmx webpage in real-time. + +SSE is a lightweight alternative to WebSockets that works over existing HTTP connections, so it is easy to use through +proxy servers and firewalls. Remember, SSE is a uni-directional service, so you cannot send any messages to an SSE +server once the connection has been established. If you need bi-directional communication, then you should consider +using [WebSockets](@web-sockets.md) instead. + +This extension replaces the experimental `hx-sse` attribute built into previous versions of htmx. For help migrating +from older versions, see the migration guide at the bottom of this page. + +Use the following attributes to configure how SSE connections behave: + +* `sse-connect=""` - The URL of the SSE server. +* `sse-swap=""` - The name of the message to swap into the DOM. +* `hx-trigger="sse:"` - SSE messages can also trigger HTTP callbacks using + the [`hx-trigger`](https://htmx.org/reference/hx-trigger.md) attribute. +* `sse-close=` - To close the EventStream gracefully when that message is received. This might be helpful + if you want to send information to a client that will eventually stop. + +## Install + +```html + + +``` + +## Usage + +```html + +
+ Contents of this box will be updated in real time + with every SSE message received from the chatroom. +
+``` + +### Connecting to an SSE Server + +To connect to an SSE server, use the `hx-ext="sse"` attribute to install the extension on that HTML element, then +add `sse-connect=""` to the element to make the connection. + +When designing your server application, remember that SSE works just like any HTTP request. Although you cannot send any +messages to the server after you have established a connection, you can send parameters to the server along with your +request. So, instead of making an SSE connection to your server at `https://my-server/chat-updates` you can also connect +to `https://my-server/chat-updates?friends=true&format=detailed`. This allows your server to customize its responses to +what your client needs. + +### Receiving Named Events + +SSE messages consist of an event name and a data packet. No other metadata is allowed in the message. Here is an +example: + +```txt +event: EventName +data:
Content to swap into your HTML page.
+``` + +We'll use the `sse-swap` attribute to listen for this event and swap its contents into our webpage. + +```html + +
+``` + +Notice that the name `EventName` from the server's message must match the value in the `sse-swap` attribute. Your server +can use as many different event names as necessary, but be careful: browsers can only listen for events that have been +explicitly named. So, if your server sends an event named `ChatroomUpdate` but your browser is only listening for events +named `ChatUpdate` then the extra event will be discarded. + +### Receiving Unnamed Events + +SSE messages can also be sent without any event name. In this case, the browser uses the default name `message` in its +place. The same rules specified above still apply. If your server sends an unnamed message, then you must listen for it +by including `sse-swap="message"`. There is no option for using a catch-all name. Here's how this looks: + +```txt +data:
Content to swap into your HTML page.
+``` + +```html + +
+``` + +### Receiving Multiple Events + +You can also listen to multiple events (named or unnamed) from a single EventSource. Listeners must be either 1) the +same element that contains the `hx-ext` and `sse-connect` attributes, or 2) child elements of the element containing +the `hx-ext` and `sse-connect` attributes. + +```html + +Multiple events in the same element +
+ +Multiple events in different elements (from the same source). +
+
+
+
+``` + +### Trigger Server Callbacks + +When a connection for server sent events has been established, child elements can listen for these events by using the +special [`hx-trigger`](https://htmx.org/reference/hx-trigger.md) syntax `sse:`. This, when combined with +an `hx-get` or similar will trigger the element to make a request. + +Here is an example: + +```html + +
+
+ ... +
+
+``` + +This example establishes an SSE connection to the `event_stream` end point which then triggers +a `GET` to the `/chatroom` url whenever the `chatter` event is seen. + +### Automatic Reconnection + +If the SSE Event Stream is closed unexpectedly, browsers are supposed to attempt to reconnect automatically. However, in +rare situations this does not work and your browser can be left hanging. This extension adds its own reconnection +logic (using an [exponential-backoff algorithm](https://en.wikipedia.org/wiki/Exponential_backoff)) on top of the +browser's automatic reconnection, so that your SSE streams will always be as reliable as possible. + +### Testing SSE Connections with the Demo Server + +Htmx includes a demo SSE server written in Node.js that will help you to see SSE in action, and begin bootstrapping your +own SSE code. It is located in the /test/ws-sse folder of the htmx distribution. Look at /test/ws-sse/README.md for +instructions on running and using the test server. + +### Migrating from Previous Versions + +Previous versions of htmx used a built-in tag `hx-sse` to implement Server Sent Events. This code has been migrated into +an extension instead. Here are the steps you need to take to migrate to this version: + +| Old Attribute | New Attribute | Comments | +|--------------------------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `hx-sse=""` | `hx-ext="sse"` | Use the `hx-ext="sse"` attribute to install the SSE extension into any HTML element. | +| `hx-sse="connect:"` | `sse-connect=""` | Add a new attribute `sse-connect` to the tag that specifies the URL of the Event Stream. This attribute must be in the same tag as the `hx-ext` attribute. | +| `hx-sse="swap:"` | `sse-swap=""` | Add a new attribute `sse-swap` to any elements that will be swapped in via the SSE extension. This attribute must be placed **on** or **inside of** the tag containing the `hx-ext` attribute. | +| `hx-trigger="sse:"` | NO CHANGE | any `hx-trigger` attributes do not need to change. The extension will identify these attributes and add listeners for any events prefixed with `sse:` | + +### Listening to events dispatched by this extension + +This extension dispatches several events. You can listen for these events like so: + +```javascript +document.body.addEventListener('htmx:sseBeforeMessage', function (e) { + // do something before the event data is swapped in +}) +``` + +Each event object has a `detail` field that contains details of the event. + +#### `htmx:sseOpen` + +This event is dispatched when an SSE connection has been successfully established. + +##### Details + +* `detail.elt` - The element on which the SSE connection was setup. This is the element which has the `sse-connect` + attribute. +* `detail.source` - The [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) object. + +#### `htmx:sseError` + +This event is dispatched when an SSE connection could not be established. + +##### Details + +* `detail.error` - The error that occured while creating + an [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource). +* `detail.source` - The [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource). + +#### `htmx:sseBeforeMessage` + +This event is dispatched just before the SSE event data is swapped into the DOM. If you don't want to swap +call `preventDefault()` on the event. Additionally the `detail` field is +a [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event) - this is the event created +by [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) when it receives an SSE message. + +##### Details + +* `detail.elt` - The swap target. + +#### `htmx:sseMessage` + +This event is dispatched after the SSE event data has been swapped into the DOM. The `detail` field is +a [MessageEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event) - this is the event created +by [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) when it receives an SSE message. + +#### `htmx:sseClose` + +This event is dispatched in three different closing scenario. To control for the scenario the user can control for the +evt.detail.sseclose property. + +```javascript +document.body.addEventListener('htmx:sseClose', function (e) { + const reason = e.detail.type + switch (reason) { + case "nodeMissing": + // Parent node is missing and therefore connection was closed + ... + case "nodeReplaced": + // Parent node replacement caused closing of connection + ... + case "message": + // connection was closed due to reception of message sse-close + ... + } +}) +``` + +##### Details + +* `detail.elt` - The swap target. + +### Additional SSE Resources + +* [Wikipedia](https://en.wikipedia.org/wiki/Server-sent_events) +* [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) +* [Can I Use?](https://caniuse.com/eventsource) diff --git a/www/content/extensions/ws.md b/www/content/extensions/ws.md new file mode 100644 index 00000000..88590e1e --- /dev/null +++ b/www/content/extensions/ws.md @@ -0,0 +1,256 @@ ++++ +title = "htmx Web Socket extension" ++++ + +The Web Sockets extension enables easy, bi-directional communication +with [Web Sockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) +servers directly from HTML. This replaces the experimental `hx-ws` attribute built into previous versions of htmx. For +help migrating from older versions, see the [Migrating](#migrating-from-previous-versions) guide at the bottom of this +page. + +Use the following attributes to configure how WebSockets behave: + +* `ws-connect=""` or `ws-connect=":"` - A URL to establish a `WebSocket` connection against. +* Prefixes `ws` or `wss` can optionally be specified. If not specified, HTMX defaults to adding the location's + scheme-type, + host and port to have browsers send cookies via websockets. +* `ws-send` - Sends a message to the nearest websocket based on the trigger value for the element (either the natural + event + or the event specified by [`hx-trigger`]) + +## Install + +```html + + +``` + +## Usage + +```html + +
+
+
+ ... +
+
+ +
+
+``` + +### Configuration + +WebSockets extension support two configuration options: + +- `createWebSocket` - a factory function that can be used to create a custom WebSocket instances. Must be a function, + returning `WebSocket` object +- `wsBinaryType` - a string value, that defines + socket's [`binaryType`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/binaryType) property. Default value + is `blob` + +### Receiving Messages from a WebSocket + +The example above establishes a WebSocket to the `/chatroom` end point. Content that is sent down from the websocket +will +be parsed as HTML and swapped in by the `id` property, using the same logic +as [Out of Band Swaps](https://htmx.org/attributes/hx-swap-oob/). + +As such, if you want to change the swapping method (e.g., append content at the end of an element or delegate swapping +to an extension), +you need to specify that in the message body, sent by the server. + +```html + +
+ ... +
+ +
+ New message received +
+ +
+ .... +
+``` + +### Sending Messages to a WebSocket + +In the example above, the form uses the `ws-send` attribute to indicate that when it is submitted, the form values +should be **serialized as JSON** +and send to the nearest enclosing `WebSocket`, in this case the `/chatroom` endpoint. + +The serialized values will include a field, `HEADERS`, that includes the headers normally submitted with an htmx +request. + +### Automatic Reconnection + +If the WebSocket is closed unexpectedly, due to `Abnormal Closure`, `Service Restart` or `Try Again Later`, this +extension will attempt to reconnect until the connection is reestablished. + +By default, the extension uses a +full-jitter [exponential-backoff algorithm](https://en.wikipedia.org/wiki/Exponential_backoff) that chooses a randomized +retry delay that grows exponentially over time. You can use a different algorithm by writing it +into `htmx.config.wsReconnectDelay`. This function takes a single parameter, the number of retries, and returns the +time (in milliseconds) to wait before trying again. + +```javascript +// example reconnect delay that you shouldn't use because +// it's not as good as the algorithm that's already in place +htmx.config.wsReconnectDelay = function (retryCount) { + return retryCount * 1000 // return value in milliseconds +} +``` + +The extension also implements a simple queuing mechanism that keeps messages in memory when the socket is not in `OPEN` +state and sends them once the connection is restored. + +### Events + +WebSockets extensions exposes a set of events that allow you to observe and customize its behavior. + +#### Event - `htmx:wsConnecting` {#htmx:wsConnecting} + +This event is triggered when a connection to a WebSocket endpoint is being attempted. + +##### Details + +* `detail.event.type` - the type of the event (`'connecting'`) + +#### Event - `htmx:wsOpen` {#htmx:wsOpen} + +This event is triggered when a connection to a WebSocket endpoint has been established. + +##### Details + +* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) +* `detail.event` - the original event from the socket +* `detail.socketWrapper` - the wrapper around socket object + +#### Event - `htmx:wsClose` {#htmx:wsClose} + +This event is triggered when a connection to a WebSocket endpoint has been closed normally. +You can check if the event was caused by an error by inspecting `detail.event` property. + +##### Details + +* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) +* `detail.event` - the original event from the socket +* `detail.socketWrapper` - the wrapper around socket object + +#### Event - `htmx:wsError` {#htmx:wsError} + +This event is triggered when `onerror` event on a socket is raised. + +##### Details + +* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) +* `detail.error` - the error object +* `detail.socketWrapper` - the wrapper around socket object + +#### Event - `htmx:wsBeforeMessage` {#htmx:wsBeforeMessage} + +This event is triggered when a message has just been received by a socket, similar to `htmx:beforeOnLoad`. This event +fires +before any processing occurs. + +If the event is cancelled, no further processing will occur. + +* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) +* `detail.message` - raw message content +* `detail.socketWrapper` - the wrapper around socket object + +#### Event - `htmx:wsAfterMessage` {#htmx:wsAfterMessage} + +This event is triggered when a message has been completely processed by htmx and all changes have been +settled, similar to `htmx:afterOnLoad`. + +Cancelling this event has no effect. + +* `detail.elt` - the element that holds the socket (the one with `ws-connect` attribute) +* `detail.message` - raw message content +* `detail.socketWrapper` - the wrapper around socket object + +#### Event - `htmx:wsConfigSend` {#htmx:wsConfigSend} + +This event is triggered when preparing to send a message from `ws-send` element. +Similarly to [`htmx:configRequest`](https://htmx.org/events#htmx:configRequest), it allows you to modify the message +before sending. + +If the event is cancelled, no further processing will occur and no messages will be sent. + +##### Details + +* `detail.parameters` - the parameters that will be submitted in the request +* `detail.unfilteredParameters` - the parameters that were found before filtering + by [`hx-select`](https://htmx.org/reference/hx-select.md) +* `detail.headers` - the request headers. Will be attached to the body in `HEADERS` property, if not falsy +* `detail.errors` - validation errors. Will prevent sending and + trigger [`htmx:validation:halted`](https://htmx.org/events#htmx:validation:halted) event if not empty +* `detail.triggeringEvent` - the event that triggered sending +* `detail.messageBody` - raw message body that will be sent to the socket. Undefined, can be set to value of any type, + supported by WebSockets. If set, will override + default JSON serialization. Useful, if you want to use some other format, like XML or MessagePack +* `detail.elt` - the element that dispatched the sending (the one with `ws-send` attribute) +* `detail.socketWrapper` - the wrapper around socket object + +#### Event - `htmx:wsBeforeSend` {#htmx:wsBeforeSend} + +This event is triggered just before sending a message. This includes messages from the queue. +Message can not be modified at this point. + +If the event is cancelled, the message will be discarded from the queue and not sent. + +##### Details + +* `detail.elt` - the element that dispatched the request (the one with `ws-connect` attribute) +* `detail.message` - the raw message content +* `detail.socketWrapper` - the wrapper around socket object + +#### Event - `htmx:wsAfterSend` {#htmx:wsAfterSend} + +This event is triggered just after sending a message. This includes messages from the queue. + +Cancelling the event has no effect. + +##### Details + +* `detail.elt` - the element that dispatched the request (the one with `ws-connect` attribute) +* `detail.message` - the raw message content +* `detail.socketWrapper` - the wrapper around socket object + +#### Socket wrapper + +You may notice that all events expose `detail.socketWrapper` property. This wrapper holds the socket +object itself and the message queue. It also encapsulates reconnection algorithm. It exposes a few members: + +- `send(message, fromElt)` - sends a message safely. If the socket is not open, the message will be persisted in the + queue + instead and sent when the socket is ready. +- `sendImmediately(message, fromElt)` - attempts to send a message regardless of socket state, bypassing the queue. May + fail +- `queue` - an array of messages, awaiting in the queue. + +This wrapper can be used in your event handlers to monitor and manipulate the queue (e.g., you can reset the queue when +reconnecting), and to send additional messages (e.g., if you want to send data in batches). +The `fromElt` parameter is optional and, when specified, will trigger corresponding websocket events from +specified element, namely `htmx:wsBeforeSend` and `htmx:wsAfterSend` events when sending your messages. + +### Testing with the Demo Server + +Htmx includes a demo WebSockets server written in Node.js that will help you to see WebSockets in action, and begin +bootstrapping your own WebSockets code. It is located in the /test/ws-sse folder of the htmx distribution. Look at +/test/ws-sse/README.md for instructions on running and using the test server. + +### Migrating from Previous Versions + +Previous versions of htmx used a built-in tag `hx-ws` to implement WebSockets. This code has been migrated into an +extension instead. Here are the steps you need to take to migrate to this version: + +| Old Attribute | New Attribute | Comments | +|-------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------| +| `hx-ws=""` | `hx-ext="ws"` | Use the `hx-ext="ws"` attribute to install the WebSockets extension into any HTML element. | +| `hx-ws="connect:"` | `ws-connect=""` | Add a new attribute `ws-connect` to the tag that defines the extension to specify the URL of the WebSockets server you're using. | +| `hx-ws="send"` | `ws-send=""` | Add a new attribute `ws-send` to mark any child forms that should send data to your WebSocket server | diff --git a/www/content/migration-guide-htmx-1.md b/www/content/migration-guide-htmx-1.md index fe0ad3d1..65e280c0 100644 --- a/www/content/migration-guide-htmx-1.md +++ b/www/content/migration-guide-htmx-1.md @@ -11,8 +11,8 @@ We place a very high value on backwards compatibility, so in most cases this mig * AMD Modules: `/dist/htmx.amd.js` * CJS Modules: `/dist/htmx.cjs.js` * The `/dist/htmx.js` file continues to be browser-loadable -* All extensions have been removed from the core htmx distribution and are distributed separately on - [their own website](https://extensions.htmx.org). While many 1.x extensions will continue to work with htmx 2, you +* All extensions have been removed from the core htmx distribution and are distributed separately. While many 1.x + extensions will continue to work with htmx 2, you must upgrade the SSE extension to the 2.x version, and it is recommended that you upgrade all of them to the 2.x versions. * If you are still using the legacy `hx-ws` and `hx-sse` attributes, please upgrade to the extension versions diff --git a/www/content/migration-guide-intercooler.md b/www/content/migration-guide-intercooler.md index 8fc3de12..81fa1faf 100644 --- a/www/content/migration-guide-intercooler.md +++ b/www/content/migration-guide-intercooler.md @@ -18,7 +18,7 @@ It is worth noting the difference in approach between what Intercooler set out t This capability is augmented in primarily 2 ways: -1. [Extensions](https://extensions.htmx.org#reference). The htmx extension framework allows for custom extensions/plugins to achieve specific functionality. An example of this is the dependencies mechanism baked into Intercooler, which is not present in htmx core. but available via [an extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md). There are also other extensions which enables new behavior that Intercooler was not capable of out the box, e.g. the [`preload` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/preload/README.md) +1. [Extensions](https://htmx.org/extensions). The htmx extension framework allows for custom extensions/plugins to achieve specific functionality. An example of this is the dependencies mechanism baked into Intercooler, which is not present in htmx core. but available via [an extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/path-deps/README.md). There are also other extensions which enables new behavior that Intercooler was not capable of out the box, e.g. the [`preload` extension](https://github.com/bigskysoftware/htmx-extensions/blob/main/src/preload/README.md) 2. Using the htmx events system with vanilla javascript, [alpine.js](https://github.com/alpinejs/alpine/) or [hyperscript](https://hyperscript.org). Hyperscript is a small, open scripting language designed to be embedded in HTML, inspired by HyperTalk and is a companion project of htmx. diff --git a/www/content/reference.md b/www/content/reference.md index 1dc01a5a..e4f6e63f 100644 --- a/www/content/reference.md +++ b/www/content/reference.md @@ -10,7 +10,7 @@ title = "Reference" * [htmx Request Headers](#request_headers) * [htmx Response Headers](#response_headers) * [htmx Events](#events) -* [htmx Extensions](https://extensions.htmx.org) +* [htmx Extensions](/extensions) * [JavaScript API](#api) * [Configuration Options](#config) @@ -188,7 +188,7 @@ All other attributes available in htmx. | [`htmx.config`](@/api.md#config) | A property that holds the current htmx config object | [`htmx.createEventSource`](@/api.md#createEventSource) | A property holding the function to create SSE EventSource objects for htmx | [`htmx.createWebSocket`](@/api.md#createWebSocket) | A property holding the function to create WebSocket objects for htmx -| [`htmx.defineExtension()`](@/api.md#defineExtension) | Defines an htmx [extension](https://extensions.htmx.org) +| [`htmx.defineExtension()`](@/api.md#defineExtension) | Defines an htmx [extension](https://htmx.org/extensions) | [`htmx.find()`](@/api.md#find) | Finds a single element matching the selector | [`htmx.findAll()` `htmx.findAll(elt, selector)`](@/api.md#find) | Finds all elements matching a given selector | [`htmx.logAll()`](@/api.md#logAll) | Installs a logger that will log all htmx events @@ -200,7 +200,7 @@ All other attributes available in htmx. | [`htmx.process()`](@/api.md#process) | Processes the given element and its children, hooking up any htmx behavior | [`htmx.remove()`](@/api.md#remove) | Removes the given element | [`htmx.removeClass()`](@/api.md#removeClass) | Removes a class from the given element -| [`htmx.removeExtension()`](@/api.md#removeExtension) | Removes an htmx [extension](https://extensions.htmx.org) +| [`htmx.removeExtension()`](@/api.md#removeExtension) | Removes an htmx [extension](https://htmx.org/extensions) | [`htmx.swap()`](@/api.md#swap) | Performs swapping (and settling) of HTML content | [`htmx.takeClass()`](@/api.md#takeClass) | Takes a class from other elements for the given element | [`htmx.toggleClass()`](@/api.md#toggleClass) | Toggles a class from the given element diff --git a/www/themes/htmx-theme/templates/page.html b/www/themes/htmx-theme/templates/page.html index 73b375db..256374fa 100644 --- a/www/themes/htmx-theme/templates/page.html +++ b/www/themes/htmx-theme/templates/page.html @@ -18,9 +18,7 @@ {% else -%} {% set show_title = true -%} {% endif -%} - {% if page.path is starting_with("/extensions/") -%} - {% set page_title = "The " ~ page.title ~ " Extension" -%} - {% elif page.path is starting_with("/attributes") -%} + {% if page.path is starting_with("/attributes") -%} {% set page_title = "" ~ page.title ~ "" -%} {% else -%} {% set page_title = page.title -%}