Ything-RepoMirrors/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2026-01-25 05:06:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

first pass over docs

Browse Source
This commit is contained in:
Carson Gross
2025-10-26 18:42:11 -06:00
parent 48dfd56501
commit 404e3861ee
12 changed files with 354 additions and 762 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@@ -85,7 +85,7 @@
* Removed extensions and moved to their own repos linked off of <https://extensions.htmx.org>
* The website now supports dark mode! (Thanks [@pokonski](https://github.com/pokonski)!)
* The older, deprecated [SSE & WS](https://v1.htmx.org/docs/#websockets-and-sse) attributes were removed
* The older, deprecated [SSE & WS](https://v1.htmx.org/docs/) attributes were removed TODO fix link
* Better support for [Web Components & Shadow DOM](https://htmx.org/examples/web-components/)
* HTTP `DELETE` requests now use parameters, rather than form encoded bodies, for their payload (This is in accordance w/ the spec.)
* Module support was split into different files:

1
dev/four/ACTIVE.md
View File

@@ -61,6 +61,7 @@
* JavaScript API audit
* Configuration options audit
* Maybe add a `:merge` option for things like `hx-indicator`, where you want to merge in parent attribute values?
* hx-disable needs it too
* Server Actions (Christian)
* Would like to create a new attribute, `hx-config`, which allows a user to override any request config value
* Consider making `__createRequestConfig` return a pure string-value object, with all non-string setup done in `handleTriggerEvent`, making

5
www/content/QUIRKS.md
View File

@@ -138,11 +138,10 @@ If you wish to include the values of the enclosing form when issuing an `GET` yo
## History Can Be Tricky
htmx provides support for interacting with the browser's [history](@/docs.md#history). This can be very powerful, but it
TODO fix link
htmx provides support for interacting with the browser's [history](@/docs.md). This can be very powerful, but it
can also be tricky, particularly if you are using 3rd party JavaScript libraries that modify the DOM.
There can also be [security concerns](@/docs.md#hx-history) when using htmx's history support.
Most of these issues can be solved by disabling any local history cache and simply issuing a server request when a
user navigates backwards in history, with the tradeoff that history navigation will be slower.

3
www/content/_index.md
View File

@@ -100,7 +100,8 @@ if(window.location.search=="?ads=true") {
<h2>introduction</h2>
htmx gives you access to [AJAX](@/docs.md#ajax), [CSS Transitions](@/docs.md#css_transitions), [WebSockets](@/docs.md#websockets-and-sse) and [Server Sent Events](@/docs.md#websockets-and-sse)
TODO fix url
htmx gives you access to [AJAX](@/docs.md#ajax), [CSS Transitions](@/docs.md#css_transitions), [WebSockets](@/docs.md) and [Server Sent Events](@/docs.md)
directly in HTML, using [attributes](@/reference.md#attributes), so you can build
[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

56
www/content/attributes/hx-disable.md
View File

@@ -1,14 +1,56 @@
+++
title = "hx-disable"
description = "The hx-disable attribute in htmx will disable htmx processing for a given element and all its children."
description = """\
The hx-disable attribute in htmx allows you to specify elements that will have the `disabled` attribute added \
to them for the duration of the request."""
+++
The `hx-disable` attribute will disable htmx processing for a given element and all its children. This can be
useful as a backup for HTML escaping, when you include user generated content in your site, and you want to
prevent malicious scripting attacks.
The `hx-disable` attribute allows you to specify elements that will have the `disabled` attribute
added to them for the duration of the request. The value of this attribute can be:
The value of the tag is ignored, and it cannot be reversed by any content beneath it.
* A CSS query selector of the element to disable.
* `this` to disable the element itself
* `closest <CSS selector>` which will find the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest)
ancestor element or itself, that matches the given CSS selector
(e.g. `closest fieldset` will disable the closest to the element `fieldset`).
* `find <CSS selector>` which will find the first child descendant element that matches the given CSS selector
* `next` which resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling)
* `next <CSS selector>` which will scan the DOM forward for the first element that matches the given CSS selector
(e.g. `next button` will disable the closest following sibling `button` element)
* `previous` which resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling)
* `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
(e.g. `previous input` will disable the closest previous sibling `input` element)
## Notes
Here is an example with a button that will disable itself during a request:
* `hx-disable` is inherited
```html
<button hx-post="/example" hx-disable="this">
Post It!
</button>
```
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-disable` 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-disable="find input[type='text'], find button">
<input type="text" placeholder="Type here...">
<button type="submit">Send</button>
</form>
```
Note that you can also use the `merge` modifier to merge parent values for a disabled elements and add additional
disabled element CSS selectors:
```html
<main hx-disable="#logout-button">
...
<form hx-post="/example" hx-disable:merge="find input[type='text'], find button">
<input type="text" placeholder="Type here...">
<button type="submit">Send</button>
</form>
</main>
```

62
www/content/attributes/hx-disabled-elt.md
View File

@@ -1,62 +0,0 @@
+++
title = "hx-disabled-elt"
description = """\
The hx-disabled-elt attribute in htmx allows you to specify elements that will have the `disabled` attribute added \
to them for the duration of the request."""
+++
The `hx-disabled-elt` attribute allows you to specify elements that will have the `disabled` attribute
added to them for the duration of the request. The value of this attribute can be:
* A CSS query selector of the element to disable.
* `this` to disable the element itself
* `closest <CSS selector>` which will find the [closest](https://developer.mozilla.org/docs/Web/API/Element/closest)
ancestor element or itself, that matches the given CSS selector
(e.g. `closest fieldset` will disable the closest to the element `fieldset`).
* `find <CSS selector>` which will find the first child descendant element that matches the given CSS selector
* `next` which resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling)
* `next <CSS selector>` which will scan the DOM forward for the first element that matches the given CSS selector
(e.g. `next button` will disable the closest following sibling `button` element)
* `previous` which resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling)
* `previous <CSS selector>` which will scan the DOM backwards for the first element that matches the given CSS selector.
(e.g. `previous input` will disable the closest previous sibling `input` element)
Here is an example with a button that will disable itself during a request:
```html
<button hx-post="/example" hx-disabled-elt="this">
Post It!
</button>
```
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:
```html
<form hx-post="/example" hx-disabled-elt="find input[type='text'], find button">
<input type="text" placeholder="Type here...">
<button type="submit">Send</button>
</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
[hx-trigger]: https://htmx.org/attributes/hx-trigger/

10
www/content/attributes/hx-ignore.md Normal file
View File

@@ -0,0 +1,10 @@
+++
title = "hx-ignore"
description = "The hx-ignore attribute in htmx will disable htmx processing for a given element and all its children."
+++
The `hx-disable` attribute will disable htmx processing for a given element and all its children. This can be
useful as a backup for HTML escaping, when you include user generated content in your site, and you want to
prevent malicious scripting attacks.
The value of the tag is ignored, and it cannot be reversed by any content beneath it.

912
www/content/docs.md
View File

File diff suppressed because it is too large Load Diff

5
www/content/migration-guide-hotwire-turbo.md
View File

@@ -41,7 +41,10 @@ addEventListener("htmx:afterOnLoad", (event) => {
## Events
* Intercepting or Pausing Events. `htmx:config-request` is equivalent to `turbo:before-fetch-request` See: [Handbook](https://turbo.hotwired.dev/handbook/drive#pausing-requests)
* `htmx:config-request` is the same as `htmx:configRequest` See: [Event Naming](@/docs.md#event_naming)
* `htmx:config-request` is the same as `htmx:configRequest`
TODO fix or remove
See: [Event Naming](@/docs.md)
```javascript
document.body.addEventListener('htmx:configRequest', (event) => {

52
www/content/reference.md
View File

@@ -42,32 +42,32 @@ All other attributes available in htmx.
<div class="info-table">
| Attribute | Description |
|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| [`hx-boost`](@/attributes/hx-boost.md) | add [progressive enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement) for links and forms |
| [`hx-confirm`](@/attributes/hx-confirm.md) | shows a `confirm()` dialog before issuing a request |
| [`hx-delete`](@/attributes/hx-delete.md) | issues a `DELETE` to the specified URL |
| [`hx-disable`](@/attributes/hx-disable.md) | disables htmx processing for the given node and any children nodes |
| [`hx-disabled-elt`](@/attributes/hx-disabled-elt.md) | adds the `disabled` attribute to the specified elements while a request is in flight |
| [`hx-disinherit`](@/attributes/hx-disinherit.md) | control and disable automatic attribute inheritance for child nodes |
| [`hx-encoding`](@/attributes/hx-encoding.md) | changes the request encoding type |
| [`hx-ext`](@/attributes/hx-ext.md) | extensions to use for this element |
| [`hx-headers`](@/attributes/hx-headers.md) | adds to the headers that will be submitted with the request |
| [`hx-history`](@/attributes/hx-history.md) | prevent sensitive data being saved to the history cache |
| [`hx-history-elt`](@/attributes/hx-history-elt.md) | the element to snapshot and restore during history navigation |
| [`hx-include`](@/attributes/hx-include.md) | include additional data in requests |
| [`hx-indicator`](@/attributes/hx-indicator.md) | the element to put the `htmx-request` class on during the request |
| [`hx-inherit`](@/attributes/hx-inherit.md) | control and enable automatic attribute inheritance for child nodes if it has been disabled by default |
| [`hx-params`](@/attributes/hx-params.md) | filters the parameters that will be submitted with a request |
| [`hx-patch`](@/attributes/hx-patch.md) | issues a `PATCH` to the specified URL |
| [`hx-preserve`](@/attributes/hx-preserve.md) | specifies elements to keep unchanged between requests |
| [`hx-prompt`](@/attributes/hx-prompt.md) | shows a `prompt()` before submitting a request |
| [`hx-put`](@/attributes/hx-put.md) | issues a `PUT` to the specified URL |
| [`hx-replace-url`](@/attributes/hx-replace-url.md) | replace the URL in the browser location bar |
| [`hx-request`](@/attributes/hx-request.md) | configures various aspects of the request |
| [`hx-sync`](@/attributes/hx-sync.md) | control how requests made by different elements are synchronized |
| [`hx-validate`](@/attributes/hx-validate.md) | force elements to validate themselves before a request |
| [`hx-vars`](@/attributes/hx-vars.md) | adds values dynamically to the parameters to submit with the request (deprecated, please use [`hx-vals`](@/attributes/hx-vals.md)) |
| Attribute | Description |
|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| [`hx-boost`](@/attributes/hx-boost.md) | add [progressive enhancement](https://en.wikipedia.org/wiki/Progressive_enhancement) for links and forms |
| [`hx-confirm`](@/attributes/hx-confirm.md) | shows a `confirm()` dialog before issuing a request |
| [`hx-delete`](@/attributes/hx-delete.md) | issues a `DELETE` to the specified URL |
| [`hx-ignore`](@/attributes/hx-ignore.md) | disables htmx processing for the given node and any children nodes |
| [`hx-disable`](@/attributes/hx-disable.md) | adds the `disabled` attribute to the specified elements while a request is in flight |
| [`hx-disinherit`](@/attributes/hx-disinherit.md) | control and disable automatic attribute inheritance for child nodes |
| [`hx-encoding`](@/attributes/hx-encoding.md) | changes the request encoding type |
| [`hx-ext`](@/attributes/hx-ext.md) | extensions to use for this element |
| [`hx-headers`](@/attributes/hx-headers.md) | adds to the headers that will be submitted with the request |
| [`hx-history`](@/attributes/hx-history.md) | prevent sensitive data being saved to the history cache |
| [`hx-history-elt`](@/attributes/hx-history-elt.md) | the element to snapshot and restore during history navigation |
| [`hx-include`](@/attributes/hx-include.md) | include additional data in requests |
| [`hx-indicator`](@/attributes/hx-indicator.md) | the element to put the `htmx-request` class on during the request |
| [`hx-inherit`](@/attributes/hx-inherit.md) | control and enable automatic attribute inheritance for child nodes if it has been disabled by default |
| [`hx-params`](@/attributes/hx-params.md) | filters the parameters that will be submitted with a request |
| [`hx-patch`](@/attributes/hx-patch.md) | issues a `PATCH` to the specified URL |
| [`hx-preserve`](@/attributes/hx-preserve.md) | specifies elements to keep unchanged between requests |
| [`hx-prompt`](@/attributes/hx-prompt.md) | shows a `prompt()` before submitting a request |
| [`hx-put`](@/attributes/hx-put.md) | issues a `PUT` to the specified URL |
| [`hx-replace-url`](@/attributes/hx-replace-url.md) | replace the URL in the browser location bar |
| [`hx-request`](@/attributes/hx-request.md) | configures various aspects of the request |
| [`hx-sync`](@/attributes/hx-sync.md) | control how requests made by different elements are synchronized |
| [`hx-validate`](@/attributes/hx-validate.md) | force elements to validate themselves before a request |
| [`hx-vars`](@/attributes/hx-vars.md) | adds values dynamically to the parameters to submit with the request (deprecated, please use [`hx-vals`](@/attributes/hx-vals.md)) |
</div>

4
www/static/src/htmx.js
View File

@@ -1290,14 +1290,14 @@ var htmx = (function() {
target: getDocument().body,
event: asString(arg1),
listener: arg2,
options: arg3
request: arg3
}
} else {
return {
target: resolveTarget(arg1),
event: asString(arg2),
listener: arg3,
options: arg4
request: arg4
}
}
}

4
www/themes/htmx-theme/static/js/htmx.js
View File

@@ -1290,14 +1290,14 @@ var htmx = (function() {
target: getDocument().body,
event: asString(arg1),
listener: arg2,
options: arg3
request: arg3
}
} else {
return {
target: resolveTarget(arg1),
event: asString(arg2),
listener: arg3,
options: arg4
request: arg4
}
}
}