Атрибут hx-swap-oob

Атрибут hx-swap-oob позволяет указать, что некоторый контент в ответе должен быть заменен в DOM в другом месте, а не в целевом элементе, то есть «вне плана». Это позволяет добавлять обновления других элементов в ответ.

Рассмотрим следующий HTML-ответ:

<div>
 ...
</div>
<div id="alerts" hx-swap-oob="true">
  Сохранено!
</div>

Первый div будет заменен в целевой элемент обычным способом. Однако второй div будет заменен как замена для элемента с id="alerts", и не окажется в целевом элементе.

Значение атрибута hx-swap-oob может быть:

true
любое допустимое значение атрибута hx-swap
любое допустимое значение атрибута hx-swap, за которым следует двоеточие и CSS-селектор

Если значение равно true или outerHTML (что эквивалентно), элемент будет заменен инлайн.

Если указано значение замены, будет использована соответствующая стратегия замены, и заключающие теги будут удалены для всех стратегий, кроме outerHTML.

Если задан селектор, будут заменены все элементы, соответствующие этому селектору. Если селектор не задан, заменится элемент с id, совпадающим с новым содержимым.

Использование альтернативных стратегий замены

Как упоминалось ранее, при использовании стратегий замены, отличных от true или outerHTML, заключающие теги удаляются. Поэтому вам необходимо обернуть возвращаемые данные в правильные теги, соответствующие контексту.

Например, при попытке вставить элемент <tr> в таблицу, которая использует <tbody>:

<tbody hx-swap-oob="beforeend:#table tbody">
  <tr>
    ...
  </tr>
</tbody>

Простая таблица:

<table hx-swap-oob="beforeend:#table2">
  <tr>
    ...
  </tr>
</table>

Элемент <li> может быть заключен в теги <ul>, <ol>, <div> или <span>. Например:

<ul hx-swap-oob="beforeend:#list1">
  <li>...</li>
</ul>

Элемент <p> может быть заключен в теги <div> или <span>:

<span hx-swap-oob="beforeend:#text">
  <p>...</p>
</span>

Проблемные таблицы и списки

Обратите внимание, что вы можете использовать тег template для инкапсуляции типов элементов, которые, согласно спецификации HTML, не могут существовать самостоятельно в DOM (<tr>, <td>, <th>, <thead>, <tbody>, <tfoot>, <colgroup>, <caption>, <col> и <li>).

Вот пример внеплановой замены строки таблицы, инкапсулированной таким образом:

<div>
  ...
</div>
<template>
  <tr id="row" hx-swap-oob="true">
    ...
  </tr>
</template>

Обратите внимание, что эти теги template будут удалены из итогового содержимого страницы.

Капризные SVG

Некоторые типы элементов, такие как SVG, используют определённое пространство имён XML для своих дочерних элементов. Это мешает корректной работе внутренних элементов при замене, если они не заключены в тег svg. Чтобы изменить внутреннее содержимое существующего SVG, вы можете использовать теги template и svg для инкапсуляции элементов, что позволяет им получить корректное пространство имён.

Вот пример внеплановой замены элементов SVG, инкапсулированных таким образом:

<div>
  ...
</div>
<template><svg>
  <circle hx-swap-oob="true" id="circle1" r="35" cx="50" cy="50" fill="red" />
</svg></template>
<template><svg hx-swap-oob="beforebegin:#circle1">
  <circle id="circle2" r="45" cx="50" cy="50" fill="blue" />
</svg></template>

Это заменит circle1 инлайн, а затем вставит circle2 перед circle1.

Обратите внимание, что эти теги template и svg, используемые для обёртывания, будут удалены из итогового содержимого страницы.

Вложенные внеплановые замены

По умолчанию любой элемент с атрибутом hx-swap-oob= в ответе обрабатывается для поведения внеплановой замены, включая случаи, когда элемент вложен в основной элемент ответа. Это может быть проблематично при использовании фрагментов шаблонов, где фрагмент может использоваться как целевой элемент для внеплановой замены, а также быть частью более крупного фрагмента. Когда более крупный фрагмент является основным ответом, внутренний фрагмент всё равно будет обработан как внеплановая замена, что приведет к его удалению из DOM.

Это поведение можно изменить, установив конфигурацию htmx.config.allowNestedOobSwaps в значение false. Если эта опция конфигурации установлена в false, внеплановые замены обрабатываются только тогда, когда элемент находится непосредственно рядом с основным элементом ответа, остальные внеплановые замены игнорируются, а атрибуты, связанные с внеплановыми заменами, удаляются.

Примечание

hx-swap-oob не наследуется