# « register_block_template en contexte headless : à quoi sert vraiment la fonction »

> register_block_template permet d'enregistrer un gabarit sans fichier theme.json complet — utile même quand le rendu final part vers un front découplé.

- Auteur : Clément Hadrot
- Publié le : 2025-05-31
- Mis à jour le : 2025-05-31
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/register-block-template-contexte-headless/

## L’essentiel

- Un gabarit sans thème complet
- Sert surtout à structurer l'admin
- Ne remplace pas le rendu front

Le Codex de WordPress décrit `register_block_template()` comme la fonction qui permet « d'enregistrer un template de bloc à la volée depuis du code, sans passer par un fichier HTML dans le dossier `templates` d'un thème ». Introduite avec WordPress 6.7 en novembre 2024, elle intrigue les équipes qui travaillent en headless : à quoi bon un gabarit de blocs si le rendu final est confié à un front React, Vue ou Svelte qui ignore tout du système de templates de WordPress ?

La réponse tient en une distinction simple, souvent mal comprise : cette fonction ne sert pas à produire du HTML affiché aux visiteurs du site découplé, mais à structurer l'expérience d'édition dans l'administration WordPress elle-même.

## Ce que fait réellement register_block_template

Un gabarit de blocs enregistré par cette fonction définit la structure par défaut proposée à l'éditeur lorsqu'il crée un nouveau contenu d'un type donné : quels blocs apparaissent déjà en place, dans quel ordre, avec quels réglages initiaux. Contrairement à un fichier `templates/single.html` classique de l'éditeur de site (FSE), `register_block_template()` s'utilise en PHP, ce qui permet de le générer dynamiquement ou de le conditionner à un contexte (rôle de l'utilisateur, valeur d'une option, etc.).

```
add_action( 'init', function() {
    register_block_template( 'mon-plugin//fiche-produit', array(
        'title'       => 'Fiche produit',
        'description' => 'Structure par défaut pour une fiche produit',
        'content'     => '<!-- wp:paragraph --><p>Description courte…</p><!-- /wp:paragraph -->',
        'post_types'  => array( 'produit' ),
    ) );
} );
```

## Pourquoi cela reste utile en headless

Sur un projet où WordPress sert exclusivement de back-office de contenu pour un front découplé, l'éditeur continue de rédiger dans Gutenberg. Proposer un gabarit de blocs cohérent au moment de la création d'une fiche produit ou d'un article guide l'équipe éditoriale vers une structure de contenu prévisible, ce qui facilite ensuite le mappage entre les blocs Gutenberg et les composants du front. Sans ce gabarit, chaque rédacteur improvise sa propre organisation de blocs, et le front doit alors gérer des variations de structure imprévues dans le contenu qu'il reçoit via l'API REST ou WPGraphQL.

> L'essentiel à retenir : Un gabarit sans thème complet ; Sert surtout à structurer l'admin ; Ne remplace pas le rendu front

## Les limites réelles de la fonction

Trois limites méritent d'être posées clairement avant d'adopter cette approche :

- `register_block_template()` influence l'écran d'édition, pas le rendu public. Un front headless qui récupère le contenu via `/wp/v2/produit/42` reçoit le HTML des blocs déjà enregistrés, indépendamment du fait qu'un gabarit ait ou non structuré leur création.
- Elle ne remplace pas un thème complet basé sur `theme.json` : un thème qui ne rend jamais de front public peut se limiter à un thème minimal (souvent qualifié de « thème d'API »), sans blocs de mise en page complexes ni styles globaux.
- Modifier un gabarit après que des contenus ont déjà été créés ne les met pas à jour rétroactivement : seuls les nouveaux contenus créés après la modification héritent de la nouvelle structure.

## Un usage concret : uniformiser une fiche produit

Sur un projet de catalogue e-commerce découplé, un gabarit enregistré pour le type `produit` peut préremplir trois blocs : un paragraphe de description courte, un bloc de liste pour les caractéristiques techniques, et un bloc de tableau pour la grille de tailles disponibles. Le rédacteur n'a plus qu'à compléter le contenu de chaque bloc, ce qui garantit que le front recevra toujours la même structure de blocs à parser, quel que soit le rédacteur à l'origine de la fiche.

## Ce qui reste hors de portée de cette fonction

Si l'objectif est de contrôler la mise en page visuelle finale (colonnes, espacement, couleurs), il faut se tourner vers `theme.json` et les styles globaux, qui s'appliquent à l'éditeur de blocs lui-même mais n'ont, eux non plus, aucun effet sur un rendu confié entièrement à un front découplé. Un gabarit de blocs structure le contenu ; il ne dessine jamais la page rendue côté visiteur.

## Notre verdict

`register_block_template()` mérite sa place dans un projet headless, mais pour une raison différente de celle qu'on lui prête souvent : elle sert à discipliner la création de contenu dans l'administration, pas à produire un rendu visuel. Utilisée ainsi, elle réduit les variations de structure que le front devrait sinon absorber, sans jamais prétendre remplacer le travail de rendu qui reste entièrement du côté de l'application découplée.