HTMX dans Drupal : avantages, mise en pratique et passage à HTMX 4

· 11 min de lecture

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_element de 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 le FormBuilder c’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 un noindex, mais n’en faites pas un lien visible ;
  • le cache fonctionne comme d’habitude : le tag node_list invalide 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 :

  1. remplacer disable() par ignore() ;
  2. puis remplacer disabledElt() par disable().

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() devient config() (hx-config) ;
  • triggerAfterSwapHeader() et triggerAfterSettleHeader() : utiliser triggerHeader() ou des écouteurs d’événements JavaScript ;
  • params() : un écouteur sur l’événement htmx:config:request ;
  • prompt() : confirm() avec un préfixe js: ;
  • inherit() et disinherit() : 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-Trigger est remplacé par HX-Source (méthode getHtmxSource()), et HX-Prompt disparaît avec getHtmxPrompt() ;
  • 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_REQUEST est 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_route est une route de fragments. Elle ne doit pas servir de page.

Checklist

  • Le site est en Drupal 11.3 ou plus (avant, la classe Htmx n’existe pas).
  • Le nouveau code interactif utilise HTMX, l’ancien #ajax n’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_route est 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() puis disabledElt() → disable(), héritage rendu explicite avec Htmx::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.