Gabarits de thème bloc : hiérarchie et gabarits sur mesure

Quand une partie d’un site sous thème bloc a besoin de sa propre mise en page, comme la catégorie News ou une page d’atterrissage de campagne, vous ajoutez un gabarit (template). Les thèmes bloc gardent leurs gabarits sous forme de fichiers HTML dans templates/, et WordPress en choisit un par URL selon la même hiérarchie que les thèmes classiques : une liste ordonnée de noms, du plus précis au plus général. Nommez le fichier d’après un slug de la hiérarchie, comme category-news.html, et il s’applique tout seul. Déclarez-le plutôt comme gabarit sur mesure dans theme.json, et les rédacteurs le choisissent page par page. Un gabarit modifié dans l’éditeur de site est enregistré dans la base de données, et cette copie l’emporte sur votre fichier.

Ce que vous allez accomplir

• Savoir quels slugs de gabarit WordPress essaie pour les types d’URL courants, et dans quel ordre.
• Lister tous les gabarits que le site peut utiliser et voir si chacun vient d’un fichier ou de la base de données.
• Ajouter un gabarit qui s’applique automatiquement à une catégorie.
• Ajouter un gabarit sur mesure que les rédacteurs peuvent assigner à n’importe quelle page, sans en-tête ni pied de page.
• Confirmer quel gabarit a affiché une URL donnée, puis retirer la sonde.

Prérequis

• WordPress 6.6 ou plus récent avec un thème bloc actif. Un thème est un thème bloc quand il contient templates/index.html. Le theme.json ci-dessous utilise la version 3 du format, qui exige 6.6 ; sur les sites 6.x plus anciens, utilisez "version": 2.
• Votre propre thème ou un thème enfant pour accueillir les fichiers. Les gabarits ajoutés à un thème téléchargé disparaissent à sa prochaine mise à jour. Créer un thème enfant prend quelques minutes. Les exemples utilisent un thème enfant nommé harbor-child, basé sur Twenty Twenty-Five.
• Un accès shell à wp-content/ et WP-CLI sur le même hôte.
• Une copie de préproduction pour l’étape 6, qui ajoute une extension obligatoire (must-use) temporaire.

Comment ça marche

Pour chaque requête, WordPress décide d’abord de quel type d’URL il s’agit : une page, un article seul, une archive de catégorie, une recherche. Il bâtit ensuite la liste des noms de gabarits, appelés slugs, pour ce type, du plus précis au plus général, et utilise le premier slug pour lequel un gabarit existe. Pour une page, un gabarit assigné passe en premier, avant tout ce qui dépend du nom de la page. index est toujours le dernier recours.

Un même slug peut être fourni par plus d’une source, et ces sources ont leur propre ordre. Une copie enregistrée depuis l’éditeur de site, stockée comme publication wp_template dans la base de données, gagne en premier. Vient ensuite un fichier du thème actif (le thème enfant, s’il y en a un), puis un fichier du thème parent. En dernier vient un gabarit enregistré par une extension avec register_block_template(), une fonction offerte depuis WordPress 6.7.

Les deux listes se combinent dans cet ordre. WordPress fixe d’abord le slug, puis la source. Une copie de page faite dans l’éditeur de site ne bat jamais un fichier page-about.html, parce que page-about est plus précis. Les gabarits PHP classiques suivent la même liste. Pour afficher la liste complète des candidats d’une requête, ou comparer avec les thèmes classiques, voyez la hiérarchie des gabarits WordPress expliquée.

Étape par étape

1. Confirmez le thème actif et l’endroit où vont vos fichiers. Les gabarits vont dans le dossier du thème actif, appelé dossier de la feuille de style (stylesheet directory) :

wp eval 'var_dump( wp_is_block_theme() ); echo get_stylesheet(), " -> parent: ", get_template(), "\n";'

Exemple de sortie :

bool(true)
harbor-child -> parent: twentytwentyfive

bool(false) veut dire qu’un thème classique est actif et que rien de ce qui suit ne s’applique. Si les deux noms sont identiques, il n’y a pas de thème enfant : créez-en un avant d’ajouter des fichiers.

2. Listez tous les gabarits que le site peut utiliser. get_block_templates() renvoie les gabarits que WordPress prendrait en compte, déjà fusionnés entre la base de données, le thème enfant, le thème parent et les extensions :

wp eval 'foreach ( get_block_templates() as $t ) { echo rtrim( sprintf( "%-15s %-7s file:%-3s %s", $t->slug, $t->source, $t->has_theme_file ? "yes" : "no", implode( ",", (array) $t->post_types ) ) ), "\n"; }'

Exemple de sortie sur un thème enfant tout neuf de Twenty Twenty-Five :

404             theme   file:yes
archive         theme   file:yes
home            theme   file:yes
index           theme   file:yes
page-no-title   theme   file:yes page
page            theme   file:yes
search          theme   file:yes
single          theme   file:yes

source vaut theme pour un fichier et custom pour une copie en base de données. Une ligne qui affiche custom et file:yes veut dire que quelqu’un a modifié ce gabarit dans l’éditeur de site, et que votre fichier est donc ignoré. La dernière colonne liste les types de publication auxquels un gabarit sur mesure peut être assigné. Gardez cette commande sous la main ; vous la relancerez.

3. Ajoutez un gabarit qui s’applique par son nom. Créez templates/category-news.html dans le thème enfant. Comme category-news est le premier slug que WordPress essaie pour la catégorie News, le fichier s’y applique automatiquement, et toutes les autres catégories gardent archive :

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","className":"tpl-category-news","layout":{"type":"constrained"}} -->
<main class="wp-block-group tpl-category-news">
	<!-- wp:query-title {"type":"archive"} /-->
	<!-- wp:paragraph -->
	<p>Company news, newest first.</p>
	<!-- /wp:paragraph -->
	<!-- wp:query {"queryId":1,"query":{"inherit":true}} -->
	<div class="wp-block-query">
		<!-- wp:post-template -->
			<!-- wp:post-title {"isLink":true} /-->
			<!-- wp:post-date /-->
			<!-- wp:post-excerpt /-->
		<!-- /wp:post-template -->
		<!-- wp:query-pagination -->
			<!-- wp:query-pagination-previous /-->
			<!-- wp:query-pagination-numbers /-->
			<!-- wp:query-pagination-next /-->
		<!-- /wp:query-pagination -->
	</div>
	<!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

"inherit":true fait afficher par la boucle de requête (Query Loop) les articles de la catégorie consultée, au lieu de lancer sa propre requête. La classe tpl-category-news est là pour que l’étape 6 puisse prouver que ce gabarit a servi. Comme category-news ne fait pas partie des noms de gabarits par défaut de WordPress, l’éditeur le propose aussi dans le menu des gabarits des articles et des pages. Personne n’a besoin de l’y choisir : il s’applique déjà à la catégorie. Confirmez que le slug de la catégorie correspond au nom du fichier :

wp term list category --slug=news --fields=term_id,slug,count

Exemple de sortie :

+---------+------+-------+
| term_id | slug | count |
+---------+------+-------+
| 7       | news | 23    |
+---------+------+-------+

Un tableau vide veut dire qu’aucune catégorie n’a le slug news. Renommez le fichier selon le vrai slug, par exemple category-company-news.html, ou utilisez l’identifiant avec category-7.html.

4. Ajoutez un gabarit sur mesure que les rédacteurs peuvent choisir. Un gabarit sur mesure n’a pas de nom dans la hiérarchie : il ne s’applique que là où quelqu’un l’assigne. Créez templates/landing.html pour des pages de campagne qui affichent le contenu de la page sans l’en-tête ni le pied de page du site :

<!-- wp:group {"tagName":"main","className":"tpl-landing","layout":{"type":"constrained"}} -->
<main class="wp-block-group tpl-landing">
	<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

Déclarez-le ensuite dans le theme.json du thème enfant, ce qui lui donne un titre lisible et le limite aux pages. Affichez d’abord les gabarits sur mesure que WordPress connaît déjà, car la liste de l’enfant est fusionnée avec celle du parent position par position :

wp eval 'echo wp_json_encode( wp_get_theme_data_custom_templates(), JSON_PRETTY_PRINT ), "\n";'

Exemple de sortie :

{
    "page-no-title": {
        "title": "Page No Title",
        "postTypes": [
            "page"
        ]
    }
}

Le parent déclare une entrée : le tableau de l’enfant doit donc la répéter en premier, puis ajouter la vôtre. Si vous ne mettez que landing dans le tableau de l’enfant, il prend la première position et remplace le page-no-title du parent. Écrivez theme.json dans le thème enfant, ou ajoutez la clé customTemplates à celui que vous avez déjà :

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"customTemplates": [
		{
			"name": "page-no-title",
			"title": "Page No Title",
			"postTypes": [ "page" ]
		},
		{
			"name": "landing",
			"title": "Landing Page",
			"postTypes": [ "page" ]
		}
	]
}

name doit être identique au nom du fichier sans .html. Quand postTypes est omis, WordPress propose le gabarit pour les pages seulement. Relancez le wp eval ; il devrait maintenant lister page-no-title et landing.

5. Assignez le gabarit sur mesure à une page. Ici, la page de campagne a l’identifiant 57. Dans l’éditeur, ouvrez la page, cliquez sur le nom du gabarit dans le panneau Page de la barre latérale, choisissez Changer de modèle, puis Landing Page dans la boîte de dialogue qui s’ouvre. En ligne de commande, le même réglage est le champ page_template, et WordPress refuse les noms qu’il ne connaît pas :

wp post update 57 --page_template=landing
wp post meta get 57 _wp_page_template

Success: Updated post 57.
landing

Error: Invalid page template. veut dire que WordPress ne propose pas landing pour ce type de publication. Vérifiez que le fichier existe, que name y correspond exactement et que postTypes inclut le type de cette publication.

6. Vérifiez quel gabarit a affiché chaque URL. En préproduction, créez wp-content/mu-plugins/sh-block-template-probe.php. Ce fichier écrit l’identifiant du gabarit courant dans le code source de la page, mais seulement quand l’URL porte ?sh-template :

<?php
add_action( 'wp_footer', function () {
	global $_wp_current_template_id;
	if ( isset( $_GET['sh-template'] ) ) {
		echo "\n<!-- block template: " . esc_html( (string) $_wp_current_template_id ) . " -->\n";
	}
} );

for u in /category/news/ /category/events/ /campaign/ /about/; do
  printf '%-18s ' "$u"
  curl -s "https://staging.example.com${u}?sh-template" | grep -o 'block template: [^ ]*'
done

Exemple de sortie :

/category/news/    block template: harbor-child//category-news
/category/events/  block template: harbor-child//archive
/campaign/         block template: harbor-child//landing
/about/            block template: harbor-child//page

L’identifiant porte toujours le nom du thème actif, même quand le fichier se trouve dans le thème parent. Servez-vous de l’étape 2 pour savoir d’où vient vraiment un slug.

Valider que ça fonctionne

Relancez la liste des gabarits de l’étape 2. Vos nouveaux fichiers devraient apparaître avec source à theme :

category-news   theme   file:yes
landing         theme   file:yes page

Confirmez ensuite que chaque page utilise le balisage que vous avez écrit, grâce aux classes ajoutées :

curl -s https://staging.example.com/category/news/ | grep -c 'tpl-category-news'
curl -s https://staging.example.com/campaign/ | grep -c 'tpl-landing'

1
1

Un 0 veut dire qu’un autre gabarit a servi ; l’étape 6 le nomme. Quand tout correspond, retirez la sonde :

rm wp-content/mu-plugins/sh-block-template-probe.php

Dépannage

Vous avez modifié un fichier de gabarit et rien n’a changé. L’étape 2 montre ce slug avec source à custom : une copie de l’éditeur de site l’emporte. Dans Apparence > Éditeur > Modèles (c’est ainsi que l’interface française nomme les gabarits), ouvrez les actions du gabarit et choisissez Réinitialiser pour revenir au fichier. Copiez d’abord dans votre fichier ce qui vaut la peine d’être gardé dans la version modifiée. Le même nœud entre fichier et base de données touche les en-têtes et les pieds de page, comme l’explique les conflits de parties de gabarit dans l’édition complète de site.

Une page a pris un gabarit que personne n’a assigné. Un gabarit sur mesure porte un nom semblable à un slug de la hiérarchie. Le page-no-title de Twenty Twenty-Five en est un exemple : une page dont le slug est no-title y correspond par son nom. Donnez aux gabarits sur mesure des noms qui ne peuvent correspondre à aucun slug, comme landing plutôt que page-landing.

Le gabarit sur mesure manque dans la liste, ou s’y affiche sous son nom de fichier. S’il manque, postTypes exclut ce type de publication, ou le fichier est mal nommé ou hors de templates/. S’il apparaît sous son slug de fichier, comme landing, WordPress a trouvé le fichier, mais pas son entrée dans theme.json. Soit name ne correspond pas au nom du fichier, soit theme.json n’est pas du JSON valide. Lancez python3 -m json.tool theme.json dans le dossier du thème enfant ; tout message d’erreur nomme la ligne fautive.

La page s’affiche vide ou annonce un gabarit vide. Depuis WordPress 6.8, les visiteurs connectés voient un message, dans la langue du site, indiquant que la page est vide parce que le gabarit est vide. Tous les autres voient une page vide. Le gabarit retenu n’a aucun bloc, en général parce qu’une copie de l’éditeur de site a été enregistrée vide. Réinitialisez-la comme dans le premier point ci-dessus, ou ajoutez des blocs au fichier si c’est le fichier lui-même qui est vide.

Le gabarit du thème parent l’emporte sur celui de l’enfant. Le fichier est dans le mauvais dossier ou n’a pas la bonne casse. Il doit se trouver dans templates/ du thème enfant, en minuscules, avec l’extension .html. Les thèmes bloc de WordPress 5.8 utilisaient block-templates/ ; le cœur lit encore ce dossier, mais gardez tout nouveau travail dans templates/.

Quand cette approche est la mauvaise

Les gabarits sont du balisage de blocs statique. Si la mise en page doit changer selon l’utilisateur, la date ou l’appareil, un gabarit n’y peut rien ; cette logique appartient à un bloc ou à du PHP. Si seule une section du contenu diffère, une composition est plus légère qu’un gabarit complet ; blocs réutilisables ou compositions synchronisées aide à choisir. Si vous écrivez une extension, enregistrez ses gabarits avec register_block_template() sur WordPress 6.7 ou plus récent, au lieu de demander aux propriétaires de sites de copier des fichiers. Un fichier de thème avec le même slug l’emporte quand même. Et si le site utilise encore un thème classique, commencez par la structure de fichiers d’un thème bloc. Les pages officielles sur la hiérarchie des gabarits et les gabarits sur mesure couvrent chaque slug et chaque option.

Un WordPress qui rapporte vraiment mérite un opérateur — Stack Harbor opère cette pile sous WordPress Entreprise ; réservez une consultation d’infrastructure.