Requêtes et Réponses

htmx s’attend à ce que les réponses aux requêtes AJAX qu’il effectue soient du HTML, généralement des fragments de HTML (bien qu’un document HTML complet, associé à une balise hx-select, puisse également être utile). htmx insérera ensuite le HTML renvoyé dans le document à l’endroit spécifié et avec la stratégie d’insertion spécifiée.

Parfois, vous pourriez souhaiter ne rien faire lors de l’insertion, mais toujours déclencher un événement côté client (voir ci-dessous).

Dans cette situation, par défaut, vous pouvez retourner un code de réponse 204 - No Content, et htmx ignorera le contenu de la réponse.

En cas de réponse d’erreur du serveur (par exemple, un 404 ou un 501), htmx déclenchera l’événement htmx:responseError, que vous pouvez gérer.

En cas d’erreur de connexion, l’événement htmx:sendError sera déclenché.

Configuration de la Gestion des Réponses

Vous pouvez configurer le comportement ci-dessus de htmx en modifiant ou en remplaçant le tableau htmx.config.responseHandling. Cet objet est une collection d’objets JavaScript définis comme suit :

    responseHandling: [
        {code: "204", swap: false},   // 204 - No Content par défaut ne fait rien, mais n'est pas une erreur
        {code: "[23]..", swap: true}, // Les réponses 200 & 300 ne sont pas des erreurs et sont échangées
        {code: "[45]..", swap: false, error: true}, // Les réponses 400 & 500 ne sont pas échangées et sont des erreurs
        {code: "...", swap: false}    // catch-all pour tout autre code de réponse
    ]

Lorsque htmx reçoit une réponse, il itérera sur le tableau htmx.config.responseHandling et testera si la propriété code d’un objet donné, lorsqu’elle est traitée comme une expression régulière, correspond à la réponse actuelle. Si une entrée correspond au code de réponse actuel, elle sera utilisée pour déterminer si et comment la réponse sera traitée.

Les champs disponibles pour la configuration de la gestion des réponses dans les entrées de ce tableau sont :

code : une chaîne représentant une expression régulière qui sera testée sur les codes de réponse.
swap : true si la réponse doit être échangée dans le DOM, false sinon.
error : true si htmx doit traiter cette réponse comme une erreur.
ignoreTitle : true si htmx doit ignorer les balises de titre dans la réponse.
select : Un sélecteur CSS à utiliser pour sélectionner le contenu de la réponse.
target : Un sélecteur CSS spécifiant une cible alternative pour la réponse.
swapOverride : Un mécanisme de remplacement pour l’échange de contenu dans la réponse.

Exemples de Configuration de la Gestion des Réponses

À titre d’exemple d’utilisation de cette configuration, considérons une situation où un framework côté serveur répond avec un code 422 - Unprocessable Entity lorsque des erreurs de validation se produisent. Par défaut, htmx ignorera la réponse, car elle correspond à l’expression régulière [45]...

Utilisant le mécanisme de configuration meta config pour configurer responseHandling, nous pourrions ajouter la configuration suivante :

<!--
  * 204 No Content par défaut ne fait rien, mais n'est pas une erreur
  * 2xx, 3xx et les réponses 422 ne sont pas des erreurs et sont échangées
  * 4xx & 5xx réponses ne sont pas échangées et sont des erreurs
  * toutes les autres réponses sont échangées en utilisant "..." comme catch-all
-->
<meta
  name="htmx-config"
  content='{
        "responseHandling":[
            {"code":"204", "swap": false},
            {"code":"[23]..", "swap": true},
            {"code":"422", "swap": true},
            {"code":"[45]..", "swap": false, "error":true},
            {"code":"...", "swap": true}
        ]
    }'
/>

Si vous souhaitiez échanger tout, quel que soit le code de réponse HTTP, vous pourriez utiliser cette configuration :

<meta name="htmx-config" content='{"responseHandling": [{"code":".*", "swap": true}]}' />
<!-- toutes les réponses sont échangées -->

Enfin, il est intéressant de considérer l’utilisation de l’extension Response Targets, qui vous permet de configurer le comportement des codes de réponse de manière déclarative via des attributs.

CORS

Lorsque vous utilisez htmx dans un contexte cross-origin, n’oubliez pas de configurer votre serveur Web pour définir les en-têtes Access-Control afin que les en-têtes htmx soient visibles côté client.

Voir tous les en-têtes de requête et de réponse implémentés par htmx.

En-têtes de Requête

htmx inclut plusieurs en-têtes utiles dans les requêtes :

En-tête	Description
`HX-Boosted`	Indique que la requête est effectuée via un élément utilisant `hx-boost`
`HX-Current-URL`	L’URL actuelle du navigateur
`HX-History-Restore-Request`	« true » si la requête est destinée à restaurer l’historique après un échec du cache d’historique local
`HX-Prompt`	La réponse de l’utilisateur à un `hx-prompt`
`HX-Request`	Toujours « true »
`HX-Target`	L’`id` de l’élément cible, s’il existe
`HX-Trigger-Name`	Le `name` de l’élément déclencheur, s’il existe
`HX-Trigger`	L’`id` de l’élément déclencheur, s’il existe

En-têtes de Réponse

htmx prend en charge certains en-têtes de réponse spécifiques à htmx :

HX-Location - permet de faire une redirection côté client sans recharger toute la page
HX-Push-Url - pousse une nouvelle URL dans la pile d’historique
HX-Redirect - peut être utilisé pour effectuer une redirection côté client vers un nouvel emplacement
HX-Refresh - si défini sur « true », le côté client fera un rafraîchissement complet de la page
HX-Replace-Url - remplace l’URL actuelle dans la barre de localisation
HX-Reswap - permet de spécifier comment la réponse sera échangée. Voir hx-swap pour les valeurs possibles
HX-Retarget - un sélecteur CSS qui met à jour la cible de la mise à jour de contenu vers un autre élément sur la page
HX-Reselect - un sélecteur CSS qui vous permet de choisir quelle partie de la réponse doit être échangée. Remplace un hx-select existant sur l’élément déclencheur
HX-Trigger - permet de déclencher des événements côté client
HX-Trigger-After-Settle - permet de déclencher des événements côté client après l’étape de stabilisation
HX-Trigger-After-Swap - permet de déclencher des événements côté client après l’étape d’échange

Pour en savoir plus sur les en-têtes HX-Trigger, consultez HX-Trigger Response Headers.

Soumettre un formulaire via htmx a l’avantage de ne plus nécessiter le Post/Redirect/Get Pattern. Après avoir traité avec succès une requête POST sur le serveur, vous n’avez pas besoin de renvoyer un [HTTP 302 (Redirect)](https://en.wikipedia.org/wiki/HTTP_

302). Vous pouvez renvoyer directement le nouveau fragment HTML.

Ordre des Opérations de Requête

L’ordre des opérations dans une requête htmx est :

L’élément est déclenché et commence une requête
- Les valeurs sont rassemblées pour la requête
- La classe htmx-request est appliquée aux éléments appropriés
- La requête est ensuite émise de manière asynchrone via AJAX
  - Lors de la réception d’une réponse, l’élément cible est marqué avec la classe htmx-swapping
  - Un délai d’échange optionnel est appliqué (voir l’attribut hx-swap)
  - L’échange de contenu réel est effectué
    - la classe htmx-swapping est supprimée de la cible
    - la classe htmx-added est ajoutée à chaque nouveau contenu
    - la classe htmx-settling est appliquée à la cible
    - Un délai de stabilisation est appliqué (par défaut : 20ms)
    - Le DOM est stabilisé
    - la classe htmx-settling est supprimée de la cible
    - la classe htmx-added est supprimée de chaque nouveau contenu

Vous pouvez utiliser les classes htmx-swapping et htmx-settling pour créer des transitions CSS entre les pages.