
Depuis Drupal 7, l’interactivité côté serveur passe par l’API Ajax de Drupal : #ajax sur un élément de formulaire, un callback qui renvoie une partie du formulaire ou une AjaxResponse remplie de commandes (ReplaceCommand, InvokeCommand…), et du JavaScript maison, historiquement basé sur jQuery, pour exécuter ces commandes dans le navigateur.
Ça fonctionne, mais c’est un protocole propre à Drupal, avec son vocabulaire et son JavaScript.
HTMX propose l’approche inverse : le serveur renvoie du HTML, et des attributs HTML décrivent quoi demander, quand, et où insérer la réponse. Pas de JSON, pas de commandes, pas de JavaScript à écrire pour les cas courants.
HTMX est entré dans le cœur de Drupal en 11.2, a reçu son API PHP en 11.3, et Drupal 12 passe à HTMX 4. Cet article fait le point : ce que ça apporte, comment l’utiliser aujourd’hui, et ce qui casse en Drupal 12.
HTMX en trente secondes
<button hx-get="/contacts/1" hx-target="#contact" hx-swap="outerHTML">
Afficher le contact
</button>
<div id="contact"></div>
Au clic, HTMX fait un GET /contacts/1, prend le HTML renvoyé et remplace #contact avec. C’est tout le modèle : une requête, un fragment HTML, un endroit où l’insérer. HTMX accepte aussi la forme data-hx-get, et c’est celle que Drupal génère.
Le calendrier dans Drupal
| Version | Ce qui arrive |
|---|---|
| Drupal 11.2 | La bibliothèque HTMX (2.0.4) entre dans le cœur, avec le JavaScript qui charge les CSS et JS des fragments renvoyés |
| Drupal 11.3 | La classe PHP Drupal\Core\Htmx\Htmx, le support des formulaires dynamiques, le rendu « contenu principal seulement », et BigPipe réécrit sur HTMX |
| Drupal 11.5 | Toujours HTMX 2, mais plusieurs méthodes de la classe Htmx sont dépréciées en préparation de HTMX 4 |
| Drupal 12.0 | HTMX 4.0.0, avec des changements incompatibles |
Le point le plus important du tableau est peut-être BigPipe. En 11.2, sa bibliothèque dépendait de core/drupal.ajax. Depuis 11.3, elle dépend de core/htmx et core/drupal.htmx. Concrètement : sur un site en 11.3 ou plus, HTMX est déjà chargé sur toutes les pages qui utilisent BigPipe, c’est-à-dire la plupart des pages vues par un utilisateur connecté.
Ce qu’HTMX apporte par rapport à l’API Ajax
Moins de JavaScript. Selon le blog officiel de Drupal core, HTMX réduit le JavaScript chargé pour ces interactions « jusqu’à 71 % », BigPipe compris. C’est un chiffre « jusqu’à », donc un meilleur cas, mais la tendance est claire.
Le serveur renvoie du HTML rendu par Drupal. Le fragment est un render array classique : thème, templates, cache, métadonnées de cache. La classe Htmx collecte même la cacheabilité des URL qu’on lui passe et l’ajoute au render array dans applyTo().
Plus de classes de commandes. Avec l’API Ajax, un comportement un peu spécifique demande souvent une commande Ajax personnalisée, côté PHP et côté JavaScript. Avec HTMX, on décrit la cible et la stratégie de remplacement par des attributs.
L’URL peut suivre l’état. HTMX sait mettre à jour la barre d’adresse (HX-Push-Url). Dans le formulaire d’export de configuration du cœur, choisir un type puis un nom de configuration met à jour l’URL : on peut la partager, recharger la page, utiliser le bouton retour.
Les behaviors continuent de fonctionner. Drupal déclenche un événement htmx:drupal:load une fois le fragment inséré et ses CSS et JS chargés, et appelle Drupal.attachBehaviors() dessus. À la suppression d’un élément, Drupal.detachBehaviors() est appelé. Vos behaviors existants s’appliquent au contenu inséré par HTMX sans rien changer.
Les assets suivent. Comme avec l’API Ajax, Drupal envoie l’état des bibliothèques déjà chargées (ajax_page_state) avec chaque requête HTMX, et la réponse n’ajoute que les CSS et JS manquants.
Les pièces de l’intégration
| Pièce | Rôle |
|---|---|
core/drupal.htmx |
La bibliothèque : HTMX plus l’intégration Drupal (assets, behaviors). Htmx::applyTo() l’attache automatiquement |
Drupal\Core\Htmx\Htmx |
Construit les attributs data-hx-* et les en-têtes de réponse HX-* sur un render array |
onlyMainContent() |
Ajoute _wrapper_format=drupal_htmx à la requête : Drupal ne renvoie que le contenu principal et ses assets, pas toute la page |
Option de route _htmx_route: TRUE |
Même chose pour toute une route : son contrôleur est toujours rendu par le renderer HTMX |
HtmxRequestInfoTrait |
Utilisé par FormBase : isHtmxRequest(), getHtmxTriggerName(), getHtmxTarget()… |
FormBuilder |
Reconnaît les requêtes HTMX (en-tête HX-Request), désactive les redirections et identifie l’élément déclencheur |
Le renderer HTMX renvoie un document HTML minimal : un <head> avec un <meta name="robots" content="noindex"> et les placeholders CSS et JS, puis un <body> qui contient les messages et le contenu principal.
Exemple 1 : un formulaire dynamique, tel que le cœur le fait
Le meilleur exemple est dans le cœur : le formulaire d’export d’une configuration (ConfigSingleExportForm, sur /admin/config/development/configuration/single/export). Choisir un type de configuration recharge la liste des noms, choisir un nom affiche le YAML. Voici la partie HTMX, simplifiée :
use Drupal\Core\Htmx\Htmx;
use Drupal\Core\Url;
$form_url = Url::fromRoute('config.export_single', [
'config_type' => $config_type,
'config_name' => $config_name,
]);
$form['config_type'] = [
'#type' => 'select',
'#title' => $this->t('Configuration type'),
'#options' => $config_types,
'#default_value' => $config_type,
];
// Quand le type change : POST du formulaire, puis on remplace
// le wrapper du select "config_name" par celui de la réponse.
(new Htmx())
->post($form_url)
->onlyMainContent()
->select('*:has(>select[name="config_name"])')
->target('*:has(>select[name="config_name"])')
->swap('outerHTML')
->applyTo($form['config_type']);
$default_type = $form_state->getValue('config_type', $config_type);
$form['config_name'] = [
'#type' => 'select',
'#title' => $this->t('Configuration name'),
'#options' => $this->findConfiguration($default_type),
'#empty_option' => $this->t('- Select -'),
];
Plus bas dans buildForm(), le formulaire regarde quel élément a déclenché la requête, et ajuste la réponse :
$trigger = $this->getHtmxTriggerName();
if ($trigger === 'config_type') {
// Vider aussi la zone d'export, "out of band" :
// HTMX la remplacera en plus de la cible principale.
(new Htmx())
->swapOob('outerHTML:[data-export-wrapper]')
->applyTo($form['export'], '#wrapper_attributes');
// Mettre à jour l'URL dans la barre d'adresse.
(new Htmx())
->pushUrlHeader(Url::fromRoute('config.export_single', [
'config_type' => $default_type,
'config_name' => '',
]))
->applyTo($form);
}
Ce qu’il faut retenir de cet exemple :
- pas de callback Ajax : c’est le même
buildForm()qui construit la page complète et la réponse HTMX ; select()choisit quoi prendre dans la réponse,target()où le mettre,swap()comment ;swapOob()met à jour une autre zone de la page dans la même réponse ;getHtmxTriggerName()remplace le#ajax+triggering_elementde l’API Ajax pour savoir ce qui a changé ;- le JavaScript de Drupal transmet le nom de l’élément déclencheur (
_triggering_element_name), donc pour leFormBuilderc’est le select qui a déclenché la requête, comme avec#ajax.
Exemple 2 : un bouton « Plus d’articles » avec _htmx_route
Deuxième cas courant : charger une suite de contenus sans recharger la page. On déclare une route dont la réponse est toujours rendue par le renderer HTMX :
# my_module.routing.yml
my_module.latest:
path: '/my-module/latest/{page}'
defaults:
_controller: '\Drupal\my_module\Controller\LatestController::page'
requirements:
_permission: 'access content'
page: '\d+'
options:
_htmx_route: TRUE
Le contrôleur renvoie un render array normal : une page d’articles et, s’il en reste, un nouveau bouton :
namespace Drupal\my_module\Controller;
use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Htmx\Htmx;
use Drupal\Core\Url;
final class LatestController extends ControllerBase {
private const PER_PAGE = 10;
public function page(int $page): array {
$storage = $this->entityTypeManager()->getStorage('node');
$ids = $storage->getQuery()
->accessCheck(TRUE)
->condition('type', 'article')
->condition('status', 1)
->sort('created', 'DESC')
// Un de plus pour savoir s'il reste une page.
->range($page * self::PER_PAGE, self::PER_PAGE + 1)
->execute();
$build = [
'#type' => 'container',
'#attributes' => ['class' => ['latest-chunk']],
'#cache' => ['tags' => ['node_list']],
];
$nodes = $storage->loadMultiple(array_slice($ids, 0, self::PER_PAGE));
$build['items'] = $this->entityTypeManager()
->getViewBuilder('node')
->viewMultiple($nodes, 'teaser');
if (count($ids) > self::PER_PAGE) {
$build['more'] = self::moreButton($page + 1);
}
return $build;
}
public static function moreButton(int $page): array {
$button = [
'#type' => 'html_tag',
'#tag' => 'button',
'#value' => t('Plus d’articles'),
'#attributes' => ['type' => 'button'],
];
// Au clic : GET de la page suivante, et le bouton est remplacé
// par le bloc .latest-chunk renvoyé (articles + nouveau bouton).
(new Htmx())
->get(Url::fromRoute('my_module.latest', ['page' => $page]))
->select('.latest-chunk')
->target('this')
->swap('outerHTML')
->applyTo($button);
return $button;
}
}
Sur la page qui affiche la première série d’articles (un bloc, un autre contrôleur), il suffit d’ajouter LatestController::moreButton(1) au render array.
Deux remarques :
- comme la route a
_htmx_route, elle renvoie toujours la réponse minimale, même si on l’ouvre directement dans le navigateur. C’est une route de fragments, pas une page. La réponse porte unnoindex, mais n’en faites pas un lien visible ; - le cache fonctionne comme d’habitude : le tag
node_listinvalide le fragment à chaque modification d’article (voir Cache API).
HTMX ou #ajax ?
API Ajax (#ajax) |
HTMX | |
|---|---|---|
| Format de réponse | JSON de commandes | HTML |
| Où vit la logique | Callback + commandes, parfois du JS | Attributs sur le render array |
| JavaScript | API Ajax de Drupal | HTMX (déjà chargé avec BigPipe en 11.3+) |
| Formulaires | Callback qui renvoie une partie du formulaire | Le même buildForm(), avec getHtmxTriggerName() |
| Mise à jour de l’URL | À la main | pushUrlHeader(), replaceUrlHeader() |
| Écosystème contrib | Partout | Encore jeune |
| Statut | Maintenue | Direction choisie par le cœur |
L’API Ajax ne disparaît pas. L’issue de planification du cœur (#3404409) prévoit de maintenir les deux tant que les modules contrib et custom n’ont pas eu le temps de migrer, potentiellement pendant plusieurs versions majeures.
Ma recommandation : pour du nouveau code, partez sur HTMX dès que le site est en 11.3 ou plus. Ne réécrivez pas l’existant juste pour le principe : un #ajax qui fonctionne peut attendre, surtout avec les cassures de HTMX 4 qui arrivent.
Drupal 12 : HTMX 4 casse des choses
C’est la partie à lire si vous écrivez du code HTMX aujourd’hui. HTMX 4 est une réécriture complète, et le change record de Drupal (HTMX now uses version 4) liste les impacts.
Le piège principal : disable() change de sens
En Drupal 11, Htmx::disable() ajoute hx-disable : « HTMX ne traite pas cet élément ». En Drupal 12, cette fonction s’appelle ignore() (hx-ignore), et disable() existe toujours, mais fait autre chose : disable(string $descriptor) désactive des éléments pendant la requête (ce que faisait disabledElt()).
Le change record demande d’appliquer les remplacements dans cet ordre :
- remplacer
disable()parignore(); - puis remplacer
disabledElt()pardisable().
Dans l’autre ordre, on transforme ses disabledElt() en disable(), puis en ignore(). Le code ne plante pas, il fait simplement autre chose.
Les méthodes supprimées
Entre Drupal 11.3 et 12.0, ces méthodes de la classe Htmx disparaissent : disabledElt(), disinherit(), inherit(), ext(), history(), params(), prompt(), request(), triggerAfterSettleHeader() et triggerAfterSwapHeader(). Elles sont marquées dépréciées en 11.5, donc PHPStan avec les règles de dépréciation les signalera.
Les remplacements principaux :
request()devientconfig()(hx-config) ;triggerAfterSwapHeader()ettriggerAfterSettleHeader(): utilisertriggerHeader()ou des écouteurs d’événements JavaScript ;params(): un écouteur sur l’événementhtmx:config:request;prompt():confirm()avec un préfixejs:;inherit()etdisinherit(): plus nécessaires, voir ci-dessous.
De nouvelles méthodes arrivent : query(), action(), method(), status(), morphSkip(), morphSkipChildren().
L’héritage devient explicite
En HTMX 2, un attribut comme hx-target posé sur un parent s’appliquait implicitement aux enfants. En HTMX 4, il faut le demander avec le modificateur :inherited. La classe Htmx de Drupal 12 expose des constantes pour ça, en dernier argument de la plupart des méthodes :
// Drupal 12 : la cible est héritée par les enfants.
(new Htmx())
->target('#results', Htmx::INHERITED)
->applyTo($form['filters']);
Si vous comptiez sur l’héritage implicite, vos enfants n’auront plus de cible en Drupal 12.
Les réponses d’erreur sont insérées
HTMX 4 insère toutes les réponses HTTP, sauf 204 et 304. Une erreur 422 ou 500 sera donc affichée dans la cible. Soignez le HTML de vos réponses d’erreur, ou utilisez status() (hx-status) pour décider du comportement par code HTTP.
En-têtes et événements
- l’en-tête de requête
HX-Triggerest remplacé parHX-Source(méthodegetHtmxSource()), etHX-Promptdisparaît avecgetHtmxPrompt(); - les noms des événements HTMX changent (minuscules séparées par des deux-points, par exemple
htmx:config:request) : tout JavaScript custom qui écoute des événements HTMX est à revoir ; - la constante
FormBuilderInterface::HTMX_REQUESTest dépréciée.
Écrire du code compatible 11 et 12
Pour un module qui doit fonctionner sur les deux versions, le change record recommande DeprecationHelper :
use Drupal\Component\Utility\DeprecationHelper;
$htmx = new Htmx();
DeprecationHelper::backwardsCompatibleCall(
\Drupal::VERSION,
'12.0.0',
fn () => $htmx->ignore(), // Drupal 12+
fn () => $htmx->disable(), // Drupal 11
);
$htmx->applyTo($element);
Les limites à connaître
- L’écosystème est jeune. La plupart des modules contrib utilisent encore
#ajax, et la documentation et les exemples HTMX spécifiques à Drupal sont encore rares. - Le code HTMX écrit pour Drupal 11 devra être revu pour Drupal 12. Si votre projet passe en 12 dans les prochains mois, écrivez directement en tenant compte de la section précédente.
- HTMX n’est pas un framework front. Pour une interface avec beaucoup d’état côté client (un éditeur, un tableau de bord très interactif), un composant JavaScript reste plus adapté. HTMX excelle quand le serveur sait rendre la réponse.
- Une route
_htmx_routeest une route de fragments. Elle ne doit pas servir de page.
Checklist
- Le site est en Drupal 11.3 ou plus (avant, la classe
Htmxn’existe pas). - Le nouveau code interactif utilise HTMX, l’ancien
#ajaxn’est migré que s’il y a une raison. - Les fragments sont des render arrays avec leurs métadonnées de cache.
onlyMainContent()ou_htmx_routeest utilisé pour ne pas renvoyer une page entière.- Le JavaScript qui doit s’appliquer au contenu inséré passe par des behaviors.
- Avant Drupal 12 :
disable()→ignore()puisdisabledElt()→disable(), héritage rendu explicite avecHtmx::INHERITED, écouteurs d’événements JavaScript renommés, réponses d’erreur vérifiées.
HTMX est probablement le changement le plus important de l’interactivité dans Drupal depuis l’arrivée de l’API Ajax. Il ne remplace pas #ajax du jour au lendemain, mais pour du nouveau code, c’est déjà la voie la plus simple, à condition de garder Drupal 12 en tête.
