From 9ec6ed4f9c5460e8eb0499968b97ef6c0253f5f6 Mon Sep 17 00:00:00 2001 From: Carson Gross Date: Tue, 18 Oct 2022 13:50:13 -0600 Subject: [PATCH] better docs --- www/extensions/head-support.md | 66 ++++++++++++++++++++++++++++++---- 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/www/extensions/head-support.md b/www/extensions/head-support.md index a5d7a73c..a48c04c7 100644 --- a/www/extensions/head-support.md +++ b/www/extensions/head-support.md @@ -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 + + + + + + +``` + +If htmx receives a request containing this new head tag: + +```html + + + + + + +``` + +Then the following operations will occur: + +* `` will be left alone +* `` will be removed from the head +* `` will be added to the head +* `` will be removed from the head +* `` will be left alone +* `` will be added to the head + +The final head element will look like this: + +```html + + + + + + +``` ### 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 + + + ``` +* 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 + + + + + ``` ### Events