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 :
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.
