Расширение `head-support`

Расширение head-support добавляет поддержку тегов head в ответах на запросы htmx.

htmx изначально был библиотекой, ориентированной на частичную замену HTML внутри тега body. Поэтому объединение дополнительной информации, такой как тег head, не было целью библиотеки. (Это в отличие, например, от TurboLinks, который был ориентирован на слияние целых веб-страниц, полученных через AJAX, в браузере.)

Атрибут hx-boost приблизил htmx к этому миру полной поддержки HTML-документов и в итоге добавила поддержку извлечения тега title из элементов head, но полная поддержка тега head никогда не была функцией библиотеки.

Это расширение устраняет этот недостаток и, вероятно, будет интегрировано в htmx для выпуска 2.0.

Установка

<script src="https://unpkg.com/htmx.org/dist/ext/head-support.js"></script>

Использование

<body hx-ext="head-support">
   ...

После установки все ответы, которые htmx получает и содержат в себе тег head, будут обрабатываться (даже если это не полные HTML-документы с корневым элементом <html>).

Обработка тега head зависит от типа запроса htmx.

Если запрос htmx исходит из элемента с атрибутом boost, используется следующий алгоритм слияния:

Элементы, которые точно совпадают с текущим содержимым head, останутся на своих местах.
Элементы, которых нет в текущем head, будут добавлены в конец тега head.
Элементы, которые есть в текущем head, но отсутствуют в новом, будут удалены из head.

Если запрос htmx исходит из элемента без атрибута boost, всё содержимое будет добавленно к существующему элементу head.

Если вы хотите переопределить это поведение в обоих случаях, вы можете поместить атрибут hx-head на новый тег <head>, используя одно из следующих двух значений:

merge - следовать алгоритму слияния, описанному выше
append - добавить элементы в конец существующего head

Управление поведением слияния

Помимо этого, вы также можете управлять поведением слияния отдельных элементов с помощью следующих атрибутов:

Если вы поместите hx-head="re-eval" на элемент head, он будет повторно добавлен (удален и добавлен) в тег head при каждом запросе, даже если он уже существует. Это может быть полезно для выполнения скрипта при каждом запросе htmx, например.
Если вы поместите hx-preserve="true" на элемент, он никогда не будет удален из head

Пример

Рассмотрим следующий тег head в существующем документе:

<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>

Если htmx получит запрос, содержащий этот новый тег head:

<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>

Тогда произойдут следующие операции:

<link rel="stylesheet" href="https://the.missing.style"> останется без изменений
<link rel="stylesheet" href="/css/site1.css"> будет удален из head
<link rel="stylesheet" href="/css/site2.css"> будет добавлен в head
<script src="/js/script1.js"></script> будет удален из head
<script src="/js/script2.js"></script> останется без изменений
<script src="/js/script3.js"></script> будет добавлен в head

Окончательный элемент head будет выглядеть так:

<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>

События

Это расширение вызывает следующие события:

htmx:removingHeadElement - срабатывает, когда элемент head собирается быть удален, при этом удаляемый элемент доступен в event.detail.headElement. Если preventDefault() вызывается на событии, элемент не будет удален.
htmx:addingHeadElement - срабатывает, когда элемент head собирается быть добавлен, при этом добавляемый элемент доступен в event.detail.headElement. Если preventDefault() вызывается на событии, элемент не будет добавлен.
htmx:afterHeadMerge - срабатывает после слияния тегов head, со следующими значениями, доступными в событии detail:
- added - добавленные элементы head
- kept - сохранённые элементы head
- removed - удалённые элементы head
htmx:beforeHeadMerge - срабатывает перед началом слияния head