# register_block_template : fournir des templates blocs depuis une extension

> WordPress 6.7 ajoute register_block_template, qui permet à une extension de fournir des templates blocs pour son CPT sans dépendre du thème actif.

- Auteur : Clément Hadrot
- Publié le : 2024-12-11
- Mis à jour le : 2024-12-11
- Catégorie : Extensions
- URL : https://wpmoderne.dev.wordpress-developpement.fr/extensions/register-block-template-templates-blocs-extension/

## L’essentiel

- Un template fourni par une extension fonctionne quel que soit le thème actif
- Le contenu s'écrit en syntaxe de blocs, comme dans l'éditeur
- L'utilisateur peut toujours surcharger le template depuis son thème

Une extension de portfolio pour architectes que nous maintenons propose un CPT « projet » avec un affichage single soigné : galerie, fiche technique, plan d'accès. Historiquement, cet affichage reposait sur un fichier `single-projet.php` copié dans le thème actif par l'utilisateur, ou sur un hook `template_include` qui forçait un fichier PHP classique — une solution qui ignorait complètement les thèmes basés sur l'éditeur de site, où l'affichage attendu est un template au format bloc, pas du PHP.

WordPress 6.7 a introduit `register_block_template()`, une fonction qui permet précisément de résoudre ce problème : une extension peut désormais enregistrer un template au format bloc directement depuis son propre code, sans dépendre du thème pour le fournir, et sans passer par un fichier PHP classique incompatible avec les thèmes FSE.

## Le problème que ça résout

Avant cette fonction, une extension qui voulait proposer un affichage single pour son CPT compatible avec l'éditeur de site n'avait que deux options peu satisfaisantes : demander à l'utilisateur de créer lui-même un template personnalisé dans l'éditeur de site (une étape de configuration en plus, souvent oubliée), ou continuer avec un template PHP classique via `template_include`, qui fonctionne mais reste à l'écart de l'écosystème des thèmes basés sur des blocs, sans hériter automatiquement du style global du thème (theme.json).

## Enregistrer un template bloc

`register_block_template()` s'utilise en indiquant un identifiant unique, un contenu au format bloc, et quelques métadonnées descriptives :

> L'essentiel à retenir : Un template fourni par une extension fonctionne quel que soit le thème actif ; Le contenu s'écrit en syntaxe de blocs, comme dans l'éditeur ; L'utilisateur peut toujours surcharger le template depuis son thème

```
add_action( 'init', function() {
    if ( ! function_exists( 'register_block_template' ) ) {
        return; // nécessite WordPress 6.7 ou supérieur
    }

    register_block_template( 'mon-extension//single-projet', array(
        'title'       => __( 'Projet (fiche architecte)', 'mon-extension' ),
        'description' => __( 'Gabarit fourni par Mon Extension pour l\'affichage des projets.', 'mon-extension' ),
        'content'     => mon_extension_contenu_template_projet(),
    ) );
} );

function mon_extension_contenu_template_projet() {
    return '<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->
</main>
<!-- /wp:group -->';
}
```

L'identifiant suit un format `espace-de-noms//nom-du-template`, où l'espace de noms correspond au slug de l'extension. WordPress résout automatiquement ce template pour l'affichage single du CPT concerné, à condition que le nom respecte les conventions de résolution de hiérarchie de templates (par exemple `single-projet` pour le CPT `projet`).

## Faire hériter le template du thème actif

Un template fourni de cette façon n'est pas figé dans le vide : il s'affiche avec le style global défini par `theme.json` du thème actif, exactement comme n'importe quel autre template bloc. C'est là tout l'intérêt par rapport à un ancien template PHP : les couleurs, les espacements et la typographie définis par le thème s'appliquent sans configuration supplémentaire.

## Laisser l'utilisateur surcharger le template

Le comportement par défaut de WordPress respecte la hiérarchie habituelle des templates : si l'utilisateur crée, depuis l'éditeur de site, un template personnalisé nommé de façon équivalente pour le même CPT, ce template personnalisé prend le pas sur celui fourni par l'extension. C'est un point important à documenter pour les utilisateurs de l'extension : le template fourni est un point de départ raisonnable, pas une contrainte définitive.

### Ajouter des blocs dynamiques propres à l'extension

Le contenu du template n'est pas limité aux blocs natifs. Si l'extension a enregistré son propre bloc (par exemple `mon-extension/fiche-technique` pour afficher la surface, le budget et les matériaux d'un projet), il s'insère de la même façon dans le contenu du template :

```
<!-- wp:mon-extension/fiche-technique /-->
```

## Comparaison avec l'ancienne approche template_include

- **template_include** : compatible avec tous les thèmes, classiques et FSE, mais nécessite d'écrire du PHP, n'hérite pas automatiquement du style global du thème, et demande de gérer soi-même le `get_header()` / `get_footer()`.
- **register_block_template** : hérite nativement du style global, s'intègre à l'éditeur de site (l'utilisateur peut visualiser et modifier le template depuis **Apparence → Éditeur**), mais nécessite WordPress 6.7 minimum et un thème compatible avec l'éditeur de site pour un rendu complet.

Pour une extension qui vise une large compatibilité, la solution la plus robuste consiste à proposer les deux, avec une détection du thème actif via `wp_is_block_theme()`, et à basculer vers `template_include` uniquement pour les thèmes classiques qui ne prennent pas en charge les templates blocs.

```
add_action( 'init', function() {
    if ( wp_is_block_theme() && function_exists( 'register_block_template' ) ) {
        // enregistrement du template bloc, comme ci-dessus
        return;
    }
    add_filter( 'template_include', 'mon_extension_template_php_classique' );
} );
```

## En résumé

`register_block_template()`, introduite dans WordPress 6.7, comble une vraie lacune pour les extensions qui fournissent un affichage dédié à leur propre type de contenu : elle permet de proposer un template natif au format bloc, hérité du style global du thème, sans jamais forcer l'utilisateur à passer par une configuration manuelle dans l'éditeur de site. Pour une nouvelle extension conçue à partir de WordPress 6.7, c'est la voie à privilégier ; pour une extension existante qui doit encore couvrir les thèmes classiques, une détection du type de thème actif permet de basculer proprement entre les deux approches.