itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-11-04 07:24:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

better docs

Browse Source
This commit is contained in:
Carson Gross 2022-10-18 13:50:13 -06:00
parent 0be011a122
commit 9ec6ed4f9c
1 changed files with 59 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
www/extensions/head-support.md
View File

@ -12,11 +12,11 @@ htmx began as a library focused on _partial replacement_ of HTML within the `bod
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) attribute moved htmx closer to this world of full-document support, and eventually
support for extracting the `title` tag out of head elements was added, but full head tag support was never part of the
library.
The [`hx-boost`](/attributes/hx-boost) 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, and will likely be integrated into htmx for the 2.0 release.
This extension addresses that shortcoming & will likely be integrated into htmx for the 2.0 release.
### Usage
@ -35,16 +35,68 @@ into the current head tag. That is:
* Elements that do not exist in the current head will be added
* Elements that exist in the current head, but not in the new head will be removed
This allows you to dynamically add JavaScript and CSS files via a head tag, for example.
#### Example
As an example, consider the following head tag in an existing document:
```html
<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site1.css">
<script src="/js/script1.js"></script>
<script src="/js/script2.js"></script>
</head>
```
If htmx receives a request containing this new head tag:
```html
<head>
<link rel="stylesheet" href="https://the.missing.style">
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script2.js"></script>
<script src="/js/script3.js"></script>
</head>
```
Then the following operations will occur:
* `<link rel="stylesheet" href="https://the.missing.style">` will be left alone
* `<link rel="stylesheet" href="/css/site1.css">` will be removed from the head
* `<link rel="stylesheet" href="/css/site2.css">` will be added to the head
* `<script src="/js/script1.js"></script>` will be removed from the head
* `<script src="/js/script2.js"></script>` will be left alone
* `<script src="/js/script3.js"></script>` will be added to the head
The final head element will look like this:
```html
<head>
<link rel="stylesheet" href="https://the.missing.style">
<script src="/js/script2.js"></script>
<link rel="stylesheet" href="/css/site2.css">
<script src="/js/script3.js"></script>
</head>
```
### Controlling Merge Behavior
Sometimes you may want to preserve an element in the head tag. You can do so using events, discussed below, but this
extension also gives you two declarative mechanisms for doing so:
* If an element in the `head` tag has an `hx-preserve="true"` attribute & value on it, it will not be removed from the head tag.
* If a new `head` element _in the content of a response_ has the `hx-swap-oob="append"` attribute & value, the content of the new
* If an element in the `head` tag has an `hx-preserve="true"` attribute & value on it, it will not be removed from the head tag:
```html
<!-- This element will not be removed even if it is not in new head content recieved from the server-->
<link rel="stylesheet" href="/css/site1.css" hx-preserve="true">
```
* If a new `head` element _in the content of a response_ has the `hx-swap-oob="beforeend"` attribute & value, the content of the new
head element will be added to the existing head tag, but no content will be removed from the existing head tag.
```html
<!-- This content will be appended to the head tag, leaving current content in place -->
<head hx-swap-oob="beforeend">
<link rel="stylesheet" href="/css/site1.css">
</head>
```
### Events