Расширение response-targets

Это расширение позволяет указывать различные целевые элементы, которые будут заменены при получении различных кодов HTTP-ответов.

Оно использует имена атрибутов в форме hx-target-[CODE], где [CODE] — числовой код HTTP-ответа с необязательным символом подстановки в конце. Вы также можете использовать hx-target-error, которое обрабатывает коды ответов 4xx и 5xx.

Значение каждого атрибута может быть:

• CSS-селектор элемента, на который нужно нацелиться.
• this, что указывает на то, что элемент, на котором находится атрибут hx-target, является целевым.
• closest <CSS selector>, который найдет ближайшего родительского предка, соответствующего заданному CSS-селектору (например, closest tr будет нацелен на ближайшую строку таблицы к элементу).
• find <CSS selector>, который найдет первый дочерний элемент-потомок, соответствующий заданному CSS-селектору.
• next <CSS selector>, который будет сканировать DOM в прямом направлении в поисках первого элемента, соответствующего заданному CSS-селектору. (Например, next .error будет нацелен на ближайший следующий элемент-сиблинг с классом error).
• previous <CSS selector>, который будет сканировать DOM в обратном направлении в поисках первого элемента, соответствующего заданному CSS-селектору. (Например, previous .error будет нацелен на ближайший предыдущий элемент-сиблинг с классом error).

Установка

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

Настройка (необязательно)

• При получении заголовка ответа HX-Retarget он отключает любой поиск, который должен был быть выполнен этим расширением, но любые ответы с ошибочными кодами состояния будут заменены (обычно они не будут, даже если целевой элемент задан через заголовок), и внутренний флаг ошибки (isError) будет изменен. Вы можете изменить это и выбрать игнорирование заголовка HX-Retarget при наличии hx-target-…, установив флаг конфигурации htmx.config.responseTargetPrefersRetargetHeader в false (по умолчанию true). Обратите внимание, что это расширение выполняет только простой проверку, установлен ли заголовок и существует ли целевой элемент. Оно не извлекает значение целевого элемента из заголовка, а доверяет, что оно было установлено логикой ядра HTMX.

• Обычно любой целевой элемент, уже установленный встроенными функциями HTMX или расширениями, вызываемыми ранее, будет перезаписан, если будет найден соответствующий тег hx-target-…. Вы можете изменить это, установив флаг конфигурации htmx.config.responseTargetPrefersExisting в true (по умолчанию false). Это рискованный вариант. Он имеет реальное применение, аналогичное опытному полнофункциональному тардиграду, поедающему скобки, когда никто не смотрит.

• Флаг isError в члене detail события, связанного с заменой содержимого с помощью hx-target-[CODE], будет установлен в false, когда получен код ошибки ответа. Это отличается от стандартного поведения. Вы можете изменить это, установив флаг конфигурации htmx.config.responseTargetUnsetsError в false (по умолчанию true).

• Флаг isError в члене detail события, связанного с заменой содержимого с помощью hx-target-[CODE], будет установлен в false, когда получен код ответа без ошибки. Это не отличается от стандартного поведения. Вы можете изменить это, установив флаг конфигурации htmx.config.responseTargetSetsError в true (по умолчанию false). Эта настройка не повлияет на код ответа 200, так как она не обрабатывается этим расширением.

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

Вот пример, который нацелен на div для нормального (200) ответа, но на другой div для ответа 404 (не найдено) и еще на один для всех кодов ответов 5xx:

<div hx-ext="response-targets">
    <div id="response-div"></div>
    <button hx-post="/register"
hx-target="#response-div"
hx-target-5*="#serious-errors"
hx-target-404="#not-found">
        Register!
    </button>
    <div id="serious-errors"></div>
    <div id="not-found"></div>
</div>

• Ответ с URL /register заменит содержимое div с помощью id response-div, когда код ответа равен 200 (OK).

• Ответ с URL /register заменит содержимое div с помощью id serious-errors, когда код ответа начинается с цифры 5 (ошибки сервера).

• Ответ с URL /register заменит содержимое div с помощью id not-found, когда код ответа равен 404 (Не найдено).

Иногда вам может не потребоваться обрабатывать ошибки 5xx и 4xx отдельно, в этом случае вы можете использовать hx-target-error.

<div hx-ext="response-targets">
    <div id="response-div"></div>
    <button hx-post="/register"
hx-target="#response-div"
hx-target-error="#any-errors">
        Register!
    </button>
    <div id="any-errors"></div>
</div>

Коды 2xx будут обрабатываться так же, как в предыдущем примере. Однако, когда код ответа равен 5xx или 4xx, ответ с /register заменит содержимое div с помощью id any-errors.

Разрешение подстановок

Когда код ответа состояния не соответствует существующему имени атрибута hx-target-[CODE], его числовая часть, выраженная в виде строки, обрезается, а последний символ заменяется на звездочку (*). Этот процесс поиска продолжается до тех пор, пока не будет найден атрибут или больше нет цифр.

Например, если браузер получает код ошибки 404, будут выполняться следующие поиски атрибутов (в указанном порядке):

• hx-target-404
• hx-target-40*
• hx-target-4*
• hx-target-*.

Если вы используете инструменты, которые не поддерживают звездочки в атрибутах HTML, вы можете использовать вместо них символ x, например, hx-target-4xx.

Примечания

• hx-target-… наследуется и может быть помещен на родительский элемент.
• hx-target-… не может использоваться для обработки кода HTTP-ответа 200.
• hx-target-… по умолчанию учитывает HX-Retarget, отдавая ему предпочтение перед любым вычисленным целевым элементом, но это можно изменить, отключив опцию конфигурации htmx.config.responseTargetPrefersRetargetHeader.
• Для избежания неожиданностей атрибут hx-ext, используемый для включения этого расширения, должен быть помещен на родительский элемент, содержащий элементы с атрибутами hx-target-… и hx-target.

См. также

• hx-target, определяет целевой элемент для замены