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

Add documentation

Browse Source 
This should document everything in the extension.  Please let me know if there are any typos or mistakes.
This commit is contained in:
Ben Pate 2021-01-01 22:08:20 -07:00
parent 3022030505
commit 8a4c2ba173
2 changed files with 81 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
www/extensions.md
View File

@ -56,6 +56,7 @@ against `htmx` in each distribution
| [`include-vals`](/extensions/include-vals) | allows you to include additional values in a request
| [`ajax-header`](/extensions/ajax-header) | includes the commonly-used `X-Requested-With` header that identifies ajax requests in many backend frameworks
| [`event-header`](/extensions/event-header) | includes a JSON serialized version of the triggering event, if any
| [`preload`](/extensions/preload) | preloads selected `href` and `hx-get` targets based on rules you control.
</div>

80
www/extensions/preload.md Normal file
View File

@ -0,0 +1,80 @@
---
layout: layout.njk
title: </> htmx - high power tools for html
---
## The `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. Its behavior can be customize 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
### Usage
Load the the `preload.js` script into your website's Javascript, and register the extension with htmx. To prevent you from accidentally preloading every link on your webpage, **you must explicityly add a "preload" attribute** to each resource you want to preload. In addition, only GET transactions are preloaded, not `POST`, `PUT`, or `DELETE`. If you use this extension and do not see resources being preloaded correctly, check these two things first.
```html
<body hx-ext="preload">
<h1>What Works</h2>
<a href="/server" preload>Requested using a standard XMLHttpRequest() and default options (below)</a>
<button hx-get="/server" preload>Request includes standard htmx headers.</button>
<h1>What WILL NOT WORK</h1>
<a href="/server">This link WILL NOT be preloaded because it does not have an explicit "preload" attribute</a>
<a hx-post="/server" preload>This resource WILL NOT be preloaded because it is an HX-POST transaction.</a>
</body>
```
### Configuration Options
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. Both options are inherited by child nodes, so (for example) you can modify them once on your `body` tag, and your settings will be used throughout your web page.
#### preload-on
This determines the event that triggers the HTML resource to be preloaded. Common options are:
* **`mouseover`** [DEFAULT] When the user's mouse moves over this resource, it triggers the resource to be preloaded. NOTE, to ensure that you do not preload resources when a mouse moves over an element quickly (for instance, while scrolling down the page) a default 100ms timeout is set on this event. If the mouse leaves the element *before* this timeout expires, then the resource is not preloaded.
* **`mousedown`** Triggers when the user presses the mouse down, but before they release the button (mouseup). This gives your server a (roughtly) 100ms head start on completing the request compared to a reguar click.
* **`load`** Triggers the preload as soon as the page (or fragment) is processed by htmx. Does not wait for a user-generated event. *Use this option sparingly.*
* **custom event names** You can also trigger preloads on any other custom events on the webpage, includeing `htmx:` events generated by htmx itself.
```html
<body hx-ext="preload" preload-on="mousedown">
<a href="/server" preload>Preloaded when the user presses the mouse down</a>
<div hx-get="/server" preload preload-on="load">Preloaded 100ms after the page/fragment is processed by htmx</div>
</body>
```
#### preload-wait
This option sets a waiting period after the triggering event fires. You can enter any timespan recognized by htmx: either in seconds (s) or milliseconds (ms), though in most cases the extension will "do the right thing" and you should not need to tune this value. Default values for this depend on the event that triggers the extension.
For **`mouseover`** events, the default for this option is **100ms**. If the user's mouse leaves the element within this time period, then the preload is canceled. This prevents resources from being preloaded when the user scrolls or moves their mouse over a large area of the page. If the user's mouse has not left the element after this time period, then the resource is preloaded. Typical users hover over links for several hundred milliseconds before they click, which leaves plenty of time for your server to generate the resource before the click event begins. [Test your own hover timing here.](http://instantclick.io/click-test)
For all other events (including **`mousedown`**, **`load`**, and other custom events) this defaults to **0ms**, which begins the preload without further delay.
```html
<body hx-ext="preload" preload-on="mouseover">
<a href="/server" preload>Preloaded 100ms after the user hovers (if they don't leave beforehand)</a>
<div hx-get="/server" preload preload-wait="0ms">Preloaded immediately after hover (though generally a bad idea)</div>
</body>
```
### About Touch Events
To accomodate touchscreen devices, an additional `ontouchstart` event handler is added whenever you specify a `mouseover` or `mousedown` trigger. This extra trigger fires immediately (no waiting period) whenever the user touches the screen, saving you 300ms of waiting time on Android, and 450ms on iOS.
### Limitations
* Links must be marked explicitly with a `preload` attribute.
* Only resources from the same server can be preloaded. Resources from third-party websites (including CDNs) will not be preloaded.
* Only `GET` transactions (including `<a href="">` and `hx-get=""`) can be preloaded. Following REST principles, `GET` transactions are assumed to not make any significant changes to a resource. Transactions that can potentially make a change (such as `POST`, `PUT`, and `DELETE`) will not be preloaded under any circumstances.
### Credits
The behavior for this plugin was inspired by the work done by [Alexandre Dieulot](https://github.com/dieulot) on [InstantClick](http://instantclick.io/), which is released under the MIT license.
### Source
<https://unpkg.com/htmx.org/dist/ext/preload.js>