Comment une extension peut-elle garantir qu’un bloc apparaît automatiquement après le bloc En-tête, sur tous les gabarits d’un thème, sans que l’utilisateur ait à l’insérer lui-même ? La fonctionnalité des Block Hooks, apparue avec WordPress 6.4 en novembre 2023, répond exactement à ce besoin. Ce guide s’adresse aux éditeurs de thèmes et d’extensions qui veulent ajouter un bloc automatiquement dans un contexte donné ; il ne traite pas de la transmission d’un projet entre développeurs.
Le principe tient en une déclaration dans block.json : plutôt que d’écrire du code qui modifie le contenu enregistré, on indique à WordPress la position relative souhaitée par rapport à un bloc cible, et le cœur se charge d’insérer virtuellement le bloc au bon endroit, au moment du rendu comme dans l’éditeur.
Étape 1 : identifier le bloc cible et la position voulue
Un Block Hook s’exprime toujours par rapport à un bloc existant, désigné par son nom complet, et une position parmi quatre valeurs possibles : before, after, firstChild ou lastChild. Pour insérer un bandeau d’alerte juste après le bloc En-tête d’un gabarit, la position recherchée est after, et le bloc cible core/template-part avec la zone header, ou plus simplement un bloc core/group identifié dans le thème.
Étape 2 : déclarer blockHooks dans block.json
La déclaration se fait dans le fichier de métadonnées du bloc à insérer, via la clé blockHooks :
{
"apiVersion": 3,
"name": "monplugin/bandeau-alerte",
"title": "Bandeau d'alerte",
"blockHooks": {
"core/template-part": "after"
}
}Cette entrée signifie : partout où un bloc core/template-part est présent dans un gabarit ou une partie de thème, insérer automatiquement le bloc monplugin/bandeau-alerte juste après lui.
Étape 3 : comprendre où le hook s’applique réellement
Les Block Hooks s’appliquent aux gabarits de thème, aux parties de thème et, sous certaines conditions, aux modèles de blocs eux-mêmes. Ils ne réécrivent jamais le contenu enregistré en base de données : l’insertion reste virtuelle, calculée au moment de l’affichage dans l’éditeur ou au moment du rendu front, ce qui permet à l’utilisateur de retirer le bloc inséré ou de le déplacer sans que WordPress ne le réinsère à chaque chargement une fois ce choix explicite fait.
Un filtre PHP pour un contrôle plus fin
Pour des besoins de logique conditionnelle plus complexes, comme n’insérer le bandeau que sur certains types de contenu, le filtre hooked_block_types permet d’intervenir en PHP, en complément ou à la place de la déclaration statique dans block.json :
add_filter(
'hooked_block_types',
function ( $hooked_blocks, $position, $anchor_block, $context ) {
if ( 'core/template-part' === $anchor_block && 'after' === $position ) {
$hooked_blocks[] = 'monplugin/bandeau-alerte';
}
return $hooked_blocks;
},
10,
4
);Étape 4 : vérifier le comportement dans l’éditeur de site
Une fois la déclaration en place, il convient d’ouvrir l’éditeur de site sur un gabarit concerné et de confirmer que le bloc apparaît bien à la position attendue, qu’il reste sélectionnable comme n’importe quel autre bloc, et que sa suppression manuelle est respectée lors des chargements suivants du même gabarit.
- Tester la position sur au moins deux gabarits différents utilisant le même bloc cible.
- Confirmer que la suppression manuelle du bloc inséré est bien mémorisée par l’éditeur.
- Vérifier le rendu front, pas uniquement l’aperçu dans l’éditeur de site.
Un Block Hook mal ciblé peut insérer un bloc à un endroit inattendu si le bloc cible existe à plusieurs reprises sur un même gabarit : mieux vaut toujours tester sur le gabarit réel du projet plutôt que sur un gabarit de démonstration.
En résumé
Les Block Hooks permettent d’automatiser l’insertion d’un bloc à un endroit précis d’un gabarit, sans jamais réécrire le contenu enregistré, grâce à une simple déclaration dans block.json complétée si besoin par le filtre hooked_block_types. Cette approche évite à l’utilisateur final d’avoir à retenir qu’un bloc doit systématiquement accompagner un autre, tout en lui laissant la liberté de le retirer s’il ne convient pas à son cas particulier.
