Formation HTMX | Envoyer une Requête AJAX

Attributs HTTP

La mécanique centrale de HTMX est d’envoyer des requêtes AJAX, sans JS. Mais alors comment faire ? Via des attributs HTML !

HTMX propose d’utiliser un ensemble de 5 attributs, associés aux verbes HTTP traditionnels, employés lors de l’implémentation d’un CRUD : GET, POST, PUT, PATCH, DELETE.

Ces attributs spéciaux permettent d’envoyer des requêtes AJAX à un serveur web.

Ils sont préfixés par hx- et suivi du verbe HTTP avec lequel on souhaite que la requête HTTP soit envoyée.

hx-[VERBE_HTTP]

La valeur associée à ces attributs représente l’URL vers laquelle on souhaite envoyer la requête HTTP.

<span hx-get="/articles">
	Voir les articles
</span>

Le simple usage de cet attribut indique au navigateur que lorsqu’un utilisateur clique sur la <span>, une requête GET est envoyée à /articles. La réponse du serveur est ensuite injectée à l’intérieur de la <span>.

Triggers

Les « triggers », traduits en français par « déclencheurs », permettent de personnaliser la manière d’envoyer une requête AJAX.

Définir un évènement

Par défaut, les requêtes AJAX sont déclenchées par l’évènement « naturel » de l’élément HTML :

• Les balises <input>, <textarea> et <select> sont déclenchées sur l’évènement change.
• Les balises <form> sont déclenchées sur l’évènement submit.
• Les autres balises sont déclenchées par l’évènement click.

Si vous souhaitez un comportement différent, vous pouvez utiliser l’attribut hx-trigger pour spécifier quel évènement déclenchera la requête.

<span hx-get="/articles" hx-trigger="dblclick">
	Voir les articles
</span>

Dans ce cas, la requête AJAX sera envoyée à la condition que la <span> soit double-cliquée.

Les valeurs possibles pour l’attribut hx-trigger correspondent aux noms traditionnels des évènements JavaScript : click, dblclick, mouseover…

Modifiers : modifier le comportement

Les modifiers permettent de modifier le comportement du trigger. Facultatifs, ils sont caractérisés par un mot-clé, noté à la suite de l’évènement.

Voici la liste des principaux modifiers :

Voir la liste intégrale sur la documentation officielle de l’attribut hx-trigger.

<input type="text" name="q"
	hx-get="/trigger_delay"
	hx-trigger="keyup"
	hx-target="#search-results"
	placeholder="Search..."
>
<div id="search-results"></div>

<input type="text" name="q"
	hx-get="/trigger_delay"
	hx-trigger="keyup changed delay:500ms"
	hx-target="#search-results"
	placeholder="Search..."
>
<div id="search-results"></div>

Filters : conditionner le déclenchement

Les filtres permettent de conditionner le déclenchement d’un évènement.

Un filtre est représenté par une expression JavaScript notée entre crochets, à la suite du nom de l’évènement.

Si l’expression est évaluée à true, l’évènement se déclenchera, sinon il ne se déclenchera pas.

click[expression_js]

Voici un exemple qui se déclenche uniquement lors d’un clic avec la touche Ctrl enfoncée sur l’élément :

<div hx-get="/demo" hx-trigger="click[ctrlKey]">
	Cliquer en maintenant la touche « Ctrl »
</div>

De la même manière, on pourrait accéder aux autres propriétés de l’objet event (target, clientX…) ou encore à this, faisant référence à l’élément courant.

Polling : déclenchement périodique

Le « polling » consiste à déclencher des requêtes HTTP périodiques pour récupérer des mises à jour du serveur sans recharger toute la page.

Ça permet d’avoir des mises à jour en temps quasi-réel, sans que l’utilisateur n’ait besoin de rafraîchir manuellement la page. C’est utile pour des fonctionnalités comme les :

• Chats en ligne
• Flux d’actualités
• Tableaux de bord
• Etc.

HTMX propose une approche relativement simple pour implémenter le polling. Pour cela, il suffit d’écrire :

hx-trigger="every <intervalle>"

Pour récupérer les messages d’un chat toutes les 5 secondes, on pourrait par exemple procéder comme ceci :

<div hx-get="/chat/235" hx-trigger="every 5s"></div>

Indicateurs

Lorsqu’une requête AJAX est en cours, une bonne pratique d’UX consiste à en informer l’utilisateur, via un loader, car le navigateur ne lui donnera aucun retour d’information. Vous pouvez accomplir cela en utilisant la classe htmx-indicator.

La classe htmx-indicator applique une opacité à 0 aux éléments la portant, les rendant invisibles mais présent dans le DOM.

<img class="htmx-indicator" src="assets/loaders/circles.svg">

Lorsqu’une requête AJAX est émise par HTMX, il ajoutera une classe htmx-request à :

• L’élément demandeur (par défaut).
• Un autre élément, si spécifié.

La classe htmx-request fera passer un élément enfant avec la classe htmx-indicator à une opacité de 1, affichant l’indicateur.

<span hx-get="/load-more">
	Afficher plus
	<img class="htmx-indicator" src="assets/loaders/circles.svg">
</span>

Lorsque la <span> est cliquée, la classe htmx-request lui sera ajoutée, ce qui révélera l’image (possédant la classe htmx-indicator).

.htmx-indicator{
	/* CSS masquant le loader */
}

.htmx-request .htmx-indicator,
.htmx-request.htmx-indicator {
	/* CSS affichant le loader */
}

Si vous souhaitez que la classe htmx-request soit ajoutée à un autre élément, vous pouvez utiliser l’attribut hx-indicator avec un sélecteur CSS pour le faire :

<span hx-get="/load-more" hx-indicator="#loader">
	Afficher plus
	<img id="loader" class="htmx-indicator" src="assets/loaders/circles.svg">
</span>