Block Hooks de WordPress 6.4 : insérer automatiquement un bloc

Un éditeur de thème block souhaitait qu’un bloc « Partage sur les réseaux » apparaisse automatiquement après chaque bloc de titre de niveau 1 en fin d’article, sur tous les contenus existants et futurs, sans demander aux rédacteurs de l’insérer manuellement à chaque fois. Avant WordPress 6.4, la seule solution robuste passait par un filtre PHP qui réécrivait le contenu du post au moment du rendu — fonctionnel, mais invisible dans l’éditeur et fragile dès que la structure de l’article changeait.

Les Block Hooks, arrivés avec WordPress 6.4 en novembre 2023, offrent une réponse déclarative à ce besoin : un bloc peut désormais indiquer, via block.json, qu’il doit s’insérer automatiquement à une position précise par rapport à un autre bloc cible, visible et modifiable directement dans l’éditeur.

Déclarer un hook dans block.json

La clé blockHooks associe le nom d’un bloc cible à une position parmi quatre valeurs possibles : before, after, firstChild ou lastChild. Pour insérer automatiquement un bloc de partage après chaque bloc core/heading de niveau 1, la déclaration ressemble à ceci :

{
    "apiVersion": 3,
    "name": "agence/partage-reseaux",
    "title": "Partage sur les réseaux",
    "category": "widgets",
    "blockHooks": {
        "core/heading": "after"
    }
}

Concrètement, dès que ce bloc est enregistré, WordPress l’insère automatiquement après chaque bloc core/heading rencontré, aussi bien dans les nouveaux articles que dans les articles existants au moment du rendu — sans jamais modifier le contenu stocké en base. L’insertion est calculée dynamiquement, ce qui signifie qu’elle disparaît proprement si l’extension est désactivée.

Cibler un bloc précis, pas toute une famille

Un piège à connaître : la clé cible un nom de bloc générique, core/heading dans l’exemple, sans distinction de niveau de titre (h1, h2, h3…). Pour restreindre l’insertion aux seuls titres de niveau 1, il faut passer par le filtre PHP hooked_block_types, qui reçoit le contexte du bloc cible et permet de renvoyer conditionnellement la liste des blocs à insérer.

add_filter(
    'hooked_block_types',
    function ( $hooked_blocks, $position, $anchor_block_type, $context ) {
        if ( 'core/heading' !== $anchor_block_type ) {
            return $hooked_blocks;
        }

        $attributs_ancre = $context instanceof WP_Block_Template
            ? array()
            : ( $context['attrs'] ?? array() );

        if ( 1 !== ( $attributs_ancre['level'] ?? 2 ) ) {
            return array_diff( $hooked_blocks, array( 'agence/partage-reseaux' ) );
        }

        return $hooked_blocks;
    },
    10,
    4
);

Ce filtre s’exécute pour chaque bloc cible rencontré et permet de retirer dynamiquement un bloc hooké de la liste selon n’importe quel critère du contexte — l’attribut level ici, mais cela pourrait tout aussi bien être le type de post ou un attribut personnalisé.

L’utilisateur garde la main

Un point important côté expérience éditoriale : un bloc inséré automatiquement par un hook reste un bloc ordinaire dans l’éditeur, que le rédacteur peut supprimer, déplacer ou modifier comme n’importe quel autre. WordPress ne force rien de façon permanente ; il propose une insertion par défaut. Si le rédacteur supprime le bloc de partage sur un article donné, WordPress retient ce choix pour cet article précis (l’information est stockée dans le contenu du post sous forme d’un attribut metadata.ignoredHookedBlocks sur le bloc ancre), sans affecter les autres articles.

Où ça s’applique aussi

• Les modèles et parties de modèle du thème block (en-tête, pied de page), un usage fréquent pour injecter un bloc de navigation ou un bandeau de consentement de façon centralisée.
• Les patterns enregistrés par thème, où un hook peut s’insérer automatiquement dans une zone de contenu type.
• Les blocs de premier niveau d’un article, en ciblant par exemple core/post-content avec la position firstChild pour insérer un bandeau en tout début de contenu.

Limites à connaître

Les Block Hooks fonctionnent en ciblant un nom de bloc, pas une instance précise identifiée par un ID : si un article contient plusieurs blocs core/heading, l’insertion se répète à chacun d’eux (sauf filtrage additionnel comme montré plus haut). Par ailleurs, cette API est pensée pour des cas d’insertion structurelle simple ; pour une logique conditionnelle complexe liée au contenu réel de l’article, une solution basée sur un rendu de bloc dynamique classique reste souvent plus lisible à maintenir.

Un conseil qu’on donne systématiquement : avant de déclarer un hook global sur un bloc natif très répandu comme core/heading, on teste d’abord sur un thème de développement avec un contenu existant volumineux pour vérifier que l’insertion ne produit pas un résultat visuellement surchargé sur des articles anciens qui n’ont pas été pensés avec ce bloc en tête.

En résumé

Les Block Hooks remplacent élégamment les anciennes manipulations de contenu par filtre PHP pour un besoin précis : insérer un bloc à un endroit prévisible par rapport à un autre, de façon réversible et visible dans l’éditeur. La clé blockHooks de block.json couvre les cas simples ; le filtre hooked_block_types prend le relais dès qu’il faut affiner la condition d’insertion selon le contexte.