# Les Block Hooks insèrent un bloc après un autre, sans intervention

> Comment déclarer un Block Hook dans block.json pour qu'une extension insère automatiquement un bloc à un endroit précis, sans toucher au contenu existant.

- Auteur : Clément Hadrot
- Publié le : 2025-07-13
- Mis à jour le : 2025-07-13
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/block-hooks-inserer-bloc-apres-un-autre/

## L’essentiel

- blockHooks se déclare directement dans block.json, sans code d'insertion manuel
- Quatre positions relatives existent : before, after, firstChild, lastChild
- Le bloc inséré reste modifiable ou supprimable par l'utilisateur final

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.

> L'essentiel à retenir : blockHooks se déclare directement dans block.json, sans code d'insertion manuel ; Quatre positions relatives existent : before, after, firstChild, lastChild ; Le bloc inséré reste modifiable ou supprimable par l'utilisateur final

## É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.