itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-10-02 07:21:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into dev

Browse Source
This commit is contained in:
carson 2021-11-12 15:32:00 -07:00
commit 8f15965797
9 changed files with 142 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/ext/preload.js
View File

@ -1,7 +1,7 @@
// This adds the "preload" extension to htmx. By default, this will
// preload the targets of any tags with `href` or `hx-get` attributes
// if they also have a `preload` attribute as well. See documentation
// for more detauls
// for more details
htmx.defineExtension("preload", {
onEvent: function(name, event) {

2
www/attributes/hx-prompt.md
View File

@ -6,7 +6,7 @@ title: </> htmx - hx-prompt
## `hx-prompt`
The `hx-prompt` attribute allows you to show a prompt before issuing a request. The value of
the prompt will be included in the requst in the `HX-Prompt` header.
the prompt will be included in the request in the `HX-Prompt` header.
Here is an example:

5
www/attributes/hx-target.md
View File

@ -28,6 +28,11 @@ Here is an example that targets a div:
The response from the `/register` url will be appended to the `div` with the id `response-div`.
This example uses `hx-target="this"` to make a link that updates itself when clicked:
```html
<a hx-post="/new-link" hx-target="this" hx-swap="outerHTML">New link</a>
```
### Notes
* `hx-target` is inherited and can be placed on a parent element

5
www/attributes/hx-trigger.md
View File

@ -88,7 +88,10 @@ The response from the `/search` url will be appended to the `div` with the id `s
There are two special events that are non-standard that htmx supports:
* `load` - triggered on load (useful for lazy-loading something)
* `revealed` - triggered when an element is scrolled into the viewport (also useful for lazy-loading)
* `revealed` - triggered when an element is scrolled into the viewport (also useful for lazy-loading). If you are using `overflow` in css like `overflow-y: scroll` you should use `intersect once` instead of `revealed`.
* `intersect` - fires once when an element first intersects the viewport. This supports two additional options:
* `root:<selector>` - a CSS selector of the root element for intersection
* `threshold:<float>` - a floating point number between 0.0 and 1.0, indicating what amount of intersection to fire the event on
### Triggering via the `HX-Trigger` header

39
www/docs.md
View File

@ -239,7 +239,7 @@ and the element will cancel the polling.
#### <a name="load_polling"></a> [Load Polling](#load_polling)
Another technique that can be used to achieve polling in htmx is "load polling", where an element specifies
an `load` trigger along with a delay, and replaces itself with the response:
a `load` trigger along with a delay, and replaces itself with the response:
```html
<div hx-get="/messages"
@ -338,7 +338,7 @@ with any of the following values:
| `beforebegin` | prepends the content before the target in the targets parent element
| `beforeend` | appends the content after the last child inside the target
| `afterend` | appends the content after the target in the targets parent element
| `none` | does not append content from response (out of band items will still be processed)
| `none` | does not append content from response ([Out of Band Swaps](#oob_swaps) and [Response Headers](##response-headers) will still be processed)
#### <a name="css_transitions"></a>[CSS Transitions](#css_transitions)
@ -628,6 +628,17 @@ event, which you can handle.
In the event of a connection error, the `htmx:sendError` event will be triggered.
### <a name="cors"></a> [CORS](#cors)
When using htmx in a cross origin context, remember to configure your web
server to set Access-Control headers in order for htmx headers to be visible
on the client side.
- [Access-Control-Allow-Headers (for request headers)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
- [Access-Control-Expose-Headers (for response headers)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers)
[See all the request and response headers that htmx implements.](/reference/#request_headers)
### <a name="request-header"></a> [Request Headers](#request-headers)
htmx includes a number of useful headers in requests:
@ -653,6 +664,9 @@ htmx supports some htmx-specific response headers:
For more on the `HX-Trigger` headers, see [`HX-Trigger` Response Headers](/headers/hx-trigger).
Submitting a form via htmx has the benefit, that the [Post/Redirect/Get Pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get) is not needed
any more. After successful processing a POST request on the server, you don't need to return a [HTTP 302 (Redirect)](https://en.wikipedia.org/wiki/HTTP_302). You can directly return the new HTML fragment.
### <a name="request-operations"></a> [Request Order of Operations](#request-operations)
The order of operations in a htmx request are:
@ -1025,6 +1039,27 @@ htmx attributes in it, you would need to add a call to `htmx.process()` like thi
.then(data => { myDiv.innerHTML = data; htmx.process(myDiv); } );
```
Some 3rd party libraries create content from HTML template elements. For instance, Alpine JS uses the `x-if`
attribute on templates to add content conditionally. Such templates are not initially part of the DOM and,
if they contain htmx attributes, will need a call to `htmx.process()` after they are loaded. The following
example uses Alpine's `$watch` function to look for a change of value that would trigger conditional content:
```html
<div x-data="{show_new: false}"
x-init="$watch('show_new', value => {
if (show_new) {
htmx.process(document.querySelector('#new_content'))
}
})">
<button @click = "show_new = !show_new">Toggle New Content</button>
<template x-if="show_new">
<div id="new_content">
<a hx-get="/server/newstuff" href="#">New Clickable</a>
</div>
</template>
</div>
```
## <a name="security"></a>[Security](#security)
htmx allows you to define logic directly in your DOM. This has a number of advantages, the

1
www/events.md
View File

@ -115,7 +115,6 @@ the documentation on [configuring swapping](/docs#modifying_swapping_behavior_wi
* `detail.elt` - the element that dispatched the request
* `detail.xhr` - the `XMLHttpRequest`
* `detail.target` - the target of the request
* `detail.requestConfig` - the configuration of the AJAX request
* `detail.shouldSwap` - if the content will be swapped (defaults to `false` for non-200 response codes)
* `detail.target` - the target of the swap

65
www/img/commspace.svg Normal file
View File

@ -0,0 +1,65 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 24.2.1, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
viewBox="0 0 841.89 206.43" style="enable-background:new 0 0 841.89 206.43;" xml:space="preserve">
<style type="text/css">
.st0{fill:#418ECC;}
.st1{fill:#4A4A4B;}
</style>
<g>
<g>
<g>
<path class="st0" d="M120.64,72.23v19.85c-3.41-4.16-6.46-7.01-9.16-8.56c-2.65-1.59-5.77-2.39-9.36-2.39
c-5.62,0-10.29,1.97-14,5.91s-5.58,8.87-5.58,14.8c0,6.06,1.79,11.04,5.38,14.93c3.63,3.9,8.25,5.85,13.87,5.85
c3.58,0,6.75-0.78,9.49-2.32c2.66-1.5,5.78-4.42,9.36-8.77v19.72c-6.06,3.14-12.12,4.71-18.19,4.71c-10,0-18.36-3.23-25.09-9.69
c-6.73-6.51-10.09-14.58-10.09-24.23s3.41-17.79,10.22-24.43c6.81-6.64,15.18-9.96,25.09-9.96
C108.96,67.65,114.98,69.18,120.64,72.23z"/>
<path class="st0" d="M216.82,69.45h14.94v5.97c2.88-3.01,5.33-5.04,7.37-6.11c2.17-1.1,4.89-1.66,8.16-1.66
c7.3,0,13.08,3.19,17.32,9.56c4.69-6.37,11.04-9.56,19.05-9.56c14.56,0,21.84,8.83,21.84,26.49v39.96h-15V98.19
c0-6.2-0.75-10.58-2.26-13.14c-1.55-2.61-4.09-3.92-7.63-3.92c-4.11,0-7.11,1.55-8.99,4.65c-1.88,3.1-2.82,8.07-2.82,14.93v33.39
h-15V98.38c0-11.51-3.32-17.26-9.96-17.26c-4.2,0-7.27,1.57-9.19,4.71c-1.92,3.15-2.89,8.1-2.89,14.87v33.39h-14.94V69.45z"/>
<path class="st0" d="M324.35,69.45h14.94v5.97c2.88-3.01,5.33-5.04,7.37-6.11c2.17-1.1,4.89-1.66,8.16-1.66
c7.3,0,13.08,3.19,17.32,9.56c4.69-6.37,11.04-9.56,19.05-9.56c14.56,0,21.84,8.83,21.84,26.49v39.96h-15V98.19
c0-6.2-0.75-10.58-2.26-13.14c-1.55-2.61-4.09-3.92-7.63-3.92c-4.11,0-7.11,1.55-8.99,4.65c-1.88,3.1-2.82,8.07-2.82,14.93v33.39
h-15V98.38c0-11.51-3.32-17.26-9.96-17.26c-4.2,0-7.27,1.57-9.19,4.71c-1.92,3.15-2.89,8.1-2.89,14.87v33.39h-14.94V69.45z"/>
<path class="st1" d="M469.45,80.46l-12.35,6.57c-1.95-3.99-4.36-5.98-7.23-5.98c-1.37,0-2.55,0.45-3.52,1.36
c-0.97,0.91-1.46,2.07-1.46,3.49c0,2.48,2.88,4.94,8.63,7.37c7.92,3.41,13.25,6.55,16,9.43c2.74,2.88,4.12,6.75,4.12,11.62
c0,6.24-2.3,11.46-6.9,15.67c-4.47,3.98-9.87,5.97-16.2,5.97c-10.84,0-18.52-5.29-23.03-15.86l12.75-5.91
c1.77,3.1,3.12,5.07,4.05,5.91c1.81,1.68,3.98,2.52,6.51,2.52c5.04,0,7.57-2.3,7.57-6.91c0-2.66-1.95-5.13-5.84-7.43
c-1.5-0.75-3.01-1.48-4.51-2.19c-1.5-0.7-3.03-1.44-4.58-2.19c-4.34-2.13-7.39-4.25-9.16-6.37c-2.26-2.7-3.38-6.17-3.38-10.42
c0-5.62,1.92-10.26,5.77-13.94c3.94-3.67,8.72-5.51,14.34-5.51C459.27,67.65,465.42,71.92,469.45,80.46z"/>
<path class="st1" d="M501.97,169.28h-14.94V69.45h14.94v7.03c5.88-5.88,12.57-8.83,20.05-8.83c8.89,0,16.22,3.27,21.97,9.83
c5.84,6.5,8.76,14.71,8.76,24.62c0,9.69-2.9,17.77-8.7,24.23c-5.75,6.42-13.01,9.63-21.77,9.63c-7.57,0-14.34-3.03-20.31-9.09
V169.28z M537.49,102.17c0-6.19-1.68-11.24-5.05-15.13c-3.41-3.94-7.7-5.91-12.88-5.91c-5.49,0-9.93,1.9-13.34,5.71
c-3.41,3.81-5.11,8.81-5.11,15c0,6.06,1.7,11.06,5.11,15c3.36,3.85,7.79,5.78,13.27,5.78c5.18,0,9.45-1.95,12.81-5.85
C535.76,112.88,537.49,108.01,537.49,102.17z"/>
<path class="st1" d="M616.21,69.45h15v64.65h-15v-6.77c-6.15,5.76-12.77,8.63-19.85,8.63c-8.94,0-16.33-3.23-22.17-9.69
c-5.8-6.6-8.7-14.82-8.7-24.69c0-9.69,2.9-17.77,8.7-24.23c5.8-6.46,13.05-9.69,21.77-9.69c7.52,0,14.27,3.1,20.24,9.29V69.45z
M580.76,101.57c0,6.19,1.66,11.24,4.98,15.13c3.41,3.94,7.7,5.91,12.88,5.91c5.53,0,10-1.91,13.41-5.71
c3.41-3.93,5.11-8.93,5.11-15c0-6.07-1.7-11.06-5.11-15c-3.41-3.85-7.83-5.78-13.27-5.78c-5.14,0-9.43,1.95-12.88,5.84
C582.47,90.91,580.76,95.77,580.76,101.57z"/>
<path class="st1" d="M700.37,72.23v19.85c-3.41-4.16-6.46-7.01-9.16-8.56c-2.65-1.59-5.77-2.39-9.36-2.39
c-5.62,0-10.29,1.97-14,5.91c-3.72,3.94-5.58,8.87-5.58,14.8c0,6.06,1.79,11.04,5.38,14.93c3.63,3.9,8.25,5.85,13.87,5.85
c3.58,0,6.75-0.78,9.49-2.32c2.66-1.5,5.78-4.42,9.36-8.77v19.72c-6.06,3.14-12.12,4.71-18.19,4.71c-10,0-18.36-3.23-25.09-9.69
c-6.73-6.51-10.09-14.58-10.09-24.23s3.41-17.79,10.22-24.43c6.81-6.64,15.18-9.96,25.09-9.96
C688.69,67.65,694.71,69.18,700.37,72.23z"/>
<path class="st1" d="M773.72,105.29h-46.33c0.4,5.31,2.12,9.54,5.18,12.68c3.05,3.09,6.97,4.65,11.75,4.65
c3.72,0,6.79-0.89,9.23-2.66c2.39-1.77,5.11-5.05,8.16-9.83l12.61,7.04c-1.95,3.32-4.01,6.16-6.17,8.53
c-2.17,2.37-4.49,4.31-6.97,5.84c-2.48,1.53-5.15,2.65-8.03,3.35c-2.88,0.71-6,1.06-9.36,1.06c-9.65,0-17.39-3.09-23.23-9.29
c-5.84-6.24-8.76-14.51-8.76-24.82c0-10.22,2.83-18.5,8.5-24.82c5.71-6.24,13.28-9.36,22.7-9.36c9.51,0,17.04,3.03,22.57,9.09
c5.49,6.02,8.23,14.36,8.23,25.02L773.72,105.29z M758.39,93.08c-2.08-7.97-7.1-11.95-15.07-11.95c-1.82,0-3.52,0.27-5.11,0.83
c-1.59,0.55-3.04,1.35-4.35,2.39c-1.31,1.04-2.42,2.29-3.35,3.75c-0.93,1.46-1.64,3.12-2.12,4.98H758.39z"/>
</g>
<g>
<g>
<path class="st0" d="M172.81,95.39c17.2,8.93,21.68,20.68,22.43,29.98c6.13-6.8,9.6-16.06,8.74-26.12
c-1.41-16.55-14.89-30-31.45-31.38c-5.8-0.48-11.32,0.48-16.26,2.55c-2.28,0.96-3.37,3.6-2.5,5.92
C155.81,81.8,160.79,89.16,172.81,95.39z"/>
<path class="st0" d="M167.24,106.12c-15.02-7.79-21.73-17.5-24.69-25.3c-5.14,6.46-8.02,14.81-7.41,23.84
c1.13,16.88,14.88,30.76,31.75,32.04c4.55,0.35,8.93-0.2,12.99-1.46c1.86-0.58,3.16-2.24,3.31-4.17
C183.77,123.58,182.45,114.01,167.24,106.12z"/>
</g>
</g>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 5.3 KiB

44
www/index.md
View File

@ -23,13 +23,12 @@ IE11 compatible
## motivation
* Why should only `<a>` and `<form>` be able to make HTTP requests?
* Why should only `click` & `submit` events trigger them?
* Why should only GET & POST be available?
* Why should you only be able to replace the *entire* screen?
* Why should only [`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) and [`<form>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) be able to make HTTP requests?
* Why should only [`click`](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event) & [`submit`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) events trigger them?
* Why should only [`GET`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) & [`POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) methods be [available](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)?
* Why should you only be able to replace the **entire** screen?
By removing these arbitrary constraints htmx completes HTML as a
[hypertext](https://en.wikipedia.org/wiki/Hypertext)
By removing these arbitrary constraints, htmx completes HTML as a [hypertext](https://en.wikipedia.org/wiki/Hypertext)
## quick start
@ -50,24 +49,35 @@ htmx is the successor to [intercooler.js](http://intercoolerjs.org)
Read the [docs introduction](/docs#introduction) for a more in-depth... introduction.
## sponsors
Thank you to our corporate sponsors!
<div class="row">
<div class="col 2" style="padding: 0">
[![CommSpace](/img/commspace.svg)](https://www.commspace.co.za/)
</div>
<div class="col 2" style="padding: 0">
</div>
<div class="col 2" style="padding: 0">
</div>
</div>
If you use htmx commercially & wish to support the
project you can sponsor us via [Github](https://github.com/sponsors/bigskysoftware)
For htmx consulting or training [email us](mailto:htmx@bigsky.software)
## haiku
*javascript fatigue:<br/>
longing for a hypertext<br/>
already in hand*
</div>
<div class="col 2" style="padding: 0">
## support
If you use htmx commercially & wish to support the
project you can sponsor us on [Github](https://github.com/sponsors/bigskysoftware)
For consulting & training on htmx, [contact us](mailto:consulting@bigsky.software)
</div>

2
www/server-examples.md
View File

@ -38,6 +38,8 @@ These examples may make it a bit easier to get started using htmx with your plat
- <https://github.com/adamchainz/django-htmx>
- <https://github.com/idlesign/django-siteajax>
- <https://github.com/guettli/django-htmx-fun/>
- <https://htmx-django.com/>
### FastAPI