diff --git a/www/content/extensions/_index.md b/www/content/extensions/_index.md deleted file mode 100644 index 8bc04f09..00000000 --- a/www/content/extensions/_index.md +++ /dev/null @@ -1,117 +0,0 @@ -+++ -title = "Extensions" -insert_anchor_links = "left" -+++ - -Htmx provides an extension mechanism for defining and using extensions within htmx-based applications. - -## Using Extensions {#using} - -Using an extension involves two steps: - - * include the extension definition, which will add it to the `htmx` extension registry - * reference the extension via the [hx-ext](@/attributes/hx-ext.md) attribute - -Here is an example - -```html - - -``` - -This loads the debug extension off of the `unpkg` CDN and then adds the debug extension to the given button. (This -will print out extensive logging for the button, for debugging purposes.) - -Note that the `hx-ext` tag may be placed on parent elements if you want a plugin to apply to an entire part of the DOM, -and on the `body` tag for it to apply to all htmx requests. - -**Tip:** To use multiple extensions on one element, separate them with a comma: - -```html - -``` - -## Ignoring Extensions {#ignoring} - -By default, extensions are applied to the DOM node where it is invoked, along with all child elements inside of that parent node. -If you need to disable an extension somewhere within the DOM tree, you can use the `ignore:` keyword to stop it from being used. - -```html -
- - -
-``` - -## Included Extensions {#included} - -htmx includes a set of extensions out of the box that address common developer needs. These extensions are tested -against `htmx` in each distribution. - -### Installing Extensions {#installing} - -You can find the source for the bundled extensions at `https://unpkg.com/browse/htmx.org@1.9.11/dist/ext/`. You will need -to include the javascript file for the extension and then install it using the [hx-ext](@/attributes/hx-ext.md) attributes. - -See the individual extension documentation for more details. - -### Included Extensions List {#reference} - -
- -| Extension | Description -|------------------------------------------------------------------|------------- -| [`ajax-header`](@/extensions/ajax-header.md) | includes the commonly-used `X-Requested-With` header that identifies ajax requests in many backend frameworks -| [`alpine-morph`](@/extensions/alpine-morph.md) | an extension for using the [Alpine.js morph](https://alpinejs.dev/plugins/morph) plugin as the swapping mechanism in htmx. -| [`class-tools`](@/extensions/class-tools.md) | an extension for manipulating timed addition and removal of classes on HTML elements -| [`client-side-templates`](@/extensions/client-side-templates.md) | support for client side template processing of JSON/XML responses -| [`debug`](@/extensions/debug.md) | an extension for debugging of a particular element using htmx -| [`event-header`](@/extensions/event-header.md) | includes a JSON serialized version of the triggering event, if any -| [`head-support`](@/extensions/head-support.md) | support for merging the `head` tag from responses into the existing documents `head` -| [`include-vals`](@/extensions/include-vals.md) | allows you to include additional values in a request -| [`json-enc`](@/extensions/json-enc.md) | use JSON encoding in the body of requests, rather than the default `x-www-form-urlencoded` -| [`idiomorph`](https://github.com/bigskysoftware/idiomorph) | an extension for using the idiomorph morphing algorithm as a swapping mechanism -| [`loading-states`](@/extensions/loading-states.md) | allows you to disable inputs, add and remove CSS classes to any element while a request is in-flight. -| [`method-override`](@/extensions/method-override.md) | use the `X-HTTP-Method-Override` header for non-`GET` and `POST` requests -| [`morphdom-swap`](@/extensions/morphdom-swap.md) | an extension for using the [morphdom](https://github.com/patrick-steele-idem/morphdom) library as the swapping mechanism in htmx. -| [`multi-swap`](@/extensions/multi-swap.md) | allows to swap multiple elements with different swap methods -| [`path-deps`](@/extensions/path-deps.md) | an extension for expressing path-based dependencies [similar to intercoolerjs](http://intercoolerjs.org/docs.html#dependencies) -| [`preload`](@/extensions/preload.md) | preloads selected `href` and `hx-get` targets based on rules you control. -| [`remove-me`](@/extensions/remove-me.md) | allows you to remove an element after a given amount of time -| [`response-targets`](@/extensions/response-targets.md) | allows to specify different target elements to be swapped when different HTTP response codes are received -| [`restored`](@/extensions/restored.md) | allows you to trigger events when the back button has been pressed -| [`server-sent-events`](@/extensions/server-sent-events.md) | uni-directional server push messaging via [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) -| [`web-sockets`](@/extensions/web-sockets.md) | bi-directional connection to WebSocket servers -| [`path-params`](@/extensions/path-params.md) | allows to use parameters for path variables instead of sending them in query or body - -
- -## Defining an Extension {#defining} - -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/ajax-header.md b/www/content/extensions/ajax-header.md deleted file mode 100644 index 8bd9838f..00000000 --- a/www/content/extensions/ajax-header.md +++ /dev/null @@ -1,21 +0,0 @@ -+++ -title = "ajax-header" -+++ - -This extension adds the `X-Requested-With` header to requests with the value "XMLHttpRequest". - -This header is commonly used by javascript frameworks to differentiate ajax requests from normal http requests. - -## Install - -```html - -``` - -## Usage - -```html - - ... - -``` diff --git a/www/content/extensions/alpine-morph.md b/www/content/extensions/alpine-morph.md deleted file mode 100644 index 5f37b1bd..00000000 --- a/www/content/extensions/alpine-morph.md +++ /dev/null @@ -1,43 +0,0 @@ -+++ -title = "alpine-morph" -+++ - -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. - -## Install - -```html - -``` - -## Usage - -```html -
- - - - - - -
- - -
-
- -
- -
-
- -``` - -In the above example, all the Alpine x-data states (count, replaced, and message) are preserved even the entire Alpine component is swapped. - -NOTE: `/swap` response from the example above should return actual element that is being replaced (this is `
-``` - -## Usage - -```html -
-
-
-
-
-
-
-``` diff --git a/www/content/extensions/client-side-templates.md b/www/content/extensions/client-side-templates.md deleted file mode 100644 index b85deb1c..00000000 --- a/www/content/extensions/client-side-templates.md +++ /dev/null @@ -1,180 +0,0 @@ -+++ -title = "client-side-templates" -+++ - -This extension supports transforming a JSON/XML request response into HTML via a client-side template before it is -swapped into the DOM. Currently four client-side templating engines are supported: - -* [mustache](https://github.com/janl/mustache.js) -* [handlebars](https://handlebarsjs.com/) -* [nunjucks](https://mozilla.github.io/nunjucks/) -* [xslt](https://developer.mozilla.org/en-US/docs/Web/XSLT) - -When you add this extension on an element, any element below it in the DOM can use one of four attributes named -`-template` (e.g. `mustache-template`) with a template ID, and the extension will resolve and render -the template the standard way for that template engine: - -* `mustache` - looks a mustache <script> tag up by ID for the template content -* `handlebars` - looks a handlebars <script> tag up by ID for the template content -* `nunjucks` - resolves the template by name via `nunjucks.render() -* `xslt` - looks an XSLT <script> tag up by ID for the template content - -The AJAX response body will be parsed as JSON/XML and passed into the template rendering. - -A second "array" version of each template is now offered, which is particularly helpful for APIs that return arrays of data. These templates are referenced as `-array-template`, and the data is accessed as `data.my_server_field`. At least in the case of `mustache`, it also enables use of loops using the `{{#data}} my_server_field {{/data}}` syntax. - -## Install - -```html - -``` - -## Usage - -```html -
- - - - -
-``` - -### Full Mustache HTML Example - -To use the client side template, you will need to include htmx, the extension, and the rendering engine. -Here is an example of this setup for Mustache using -a [`