« Comment une extension peut-elle fournir un gabarit d’affichage complet sans obliger le développeur du thème à copier un fichier dans son propre dossier ? » C’est exactement le problème que résout register_block_template(), une fonction ajoutée à WordPress 6.7 en novembre 2024, pensée pour les auteurs d’extensions qui veulent apporter leur propre modèle d’affichage sans dépendre de la structure de fichiers du thème actif.
Le cas concret : une extension de gestion immobilière qui enregistre un type de contenu bien et souhaite fournir, par défaut, un gabarit de fiche complet (galerie photo, prix, surface, carte de localisation) utilisable immédiatement par n’importe quel thème de blocs, sans configuration préalable côté client.
Avant WordPress 6.7 : la contrainte du dossier de thème
Historiquement, un gabarit personnalisé (au sens des templates de l’éditeur de site) devait exister sous forme de fichier HTML dans le dossier templates du thème actif, ou être créé manuellement par l’utilisateur depuis l’éditeur de site. Une extension ne pouvait donc pas fournir un gabarit « prêt à l’emploi » sans demander au développeur du thème d’aller copier un fichier fourni par l’extension dans son propre thème, une manipulation fragile et facilement oubliée lors d’une mise à jour de thème.
Enregistrer un gabarit directement depuis le code de l’extension
register_block_template() permet d’enregistrer un gabarit complet, avec son contenu au format blocs, directement depuis le code PHP de l’extension, sans jamais toucher au dossier du thème. Le gabarit devient immédiatement disponible dans la liste des modèles de l’éditeur de site, comme s’il provenait du thème lui-même :
add_action( 'init', function() {
register_block_template( 'immobilier-pro//single-bien', array(
'title' => 'Fiche bien immobilier',
'description' => 'Gabarit fourni par l\'extension Immobilier Pro pour l\'affichage d\'un bien.',
'content' => '<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
<!-- wp:post-title /-->
<!-- wp:post-featured-image /-->
</div>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer"} /-->',
) );
} );Le premier argument suit un format précis : le nom de l’extension (utilisé comme espace de noms), suivi de deux barres obliques puis du slug du gabarit. Cette convention évite toute collision entre plusieurs extensions qui déclareraient chacune un gabarit du même nom.
Un gabarit qui reste modifiable par le client
Un point rassurant pour le développeur qui craint de perdre la main sur la personnalisation : un gabarit enregistré via cette fonction reste modifiable depuis l’éditeur de site, exactement comme s’il provenait d’un fichier du thème. Si le client personnalise le gabarit, cette version personnalisée est enregistrée en base de données et prend le pas sur la version fournie par l’extension, tout en conservant la possibilité de revenir à la version d’origine via l’option « réinitialiser » de l’éditeur.
Priorité entre extension et thème
Si le thème actif fournit déjà un fichier single-bien.html dans son propre dossier de gabarits, celui du thème garde la priorité sur celui enregistré par l’extension : le mécanisme respecte la hiérarchie habituelle, où le thème reste toujours l’autorité finale sur l’apparence du site. Cela permet à un développeur de thème de surcharger, s’il le souhaite, le gabarit fourni par l’extension sans configuration supplémentaire.
| Source du gabarit | Priorité |
|---|---|
| Fichier du thème actif | Maximale |
| Gabarit enregistré par une extension | Utilisé si le thème n’en fournit pas |
| Gabarit générique du cœur WordPress | Utilisé en dernier recours |
Limites à connaître
Cette fonction enregistre un gabarit complet, pas un fragment réutilisable ailleurs : pour cela, il existe un mécanisme distinct destiné aux template parts, qui répond à un besoin différent et ne sera pas détaillé ici. Il faut également garder à l’esprit que le contenu du gabarit, écrit en dur dans le code PHP sous forme de chaîne de caractères, devient rapidement difficile à maintenir lisiblement au-delà de quelques blocs simples ; charger ce contenu depuis un fichier séparé du dossier de l’extension via file_get_contents() reste une meilleure pratique pour un gabarit plus complexe.
Un gabarit fourni par une extension doit toujours rester une proposition raisonnable, jamais une contrainte : la possibilité pour le thème de le surclasser est ce qui rend cette fonction réellement utilisable en production.
En résumé
register_block_template(), disponible depuis WordPress 6.7, change la façon dont une extension peut fournir un gabarit d’affichage complet : plus besoin de demander au développeur du thème de copier un fichier, le gabarit s’enregistre en PHP et reste personnalisable depuis l’éditeur de site comme n’importe quel autre modèle natif.
