Chapitre 5.4 — La hiérarchie de gabarits

⏱️ TL;DR — La hiérarchie de gabarits (template hierarchy) est le système par lequel WordPress choisit quel fichier de template utiliser pour rendre une page, selon le type de contenu demandé et une cascade du plus spécifique au plus général. Pour un article seul : single-{type}-{slug}.php → single-{type}.php → single.php → singular.php → index.php. Le premier fichier existant gagne ; index.php est le filet universel. C’est un routing par convention de nommage — le connaître, c’est savoir quel fichier créer pour personnaliser telle vue.

🎯 Objectifs

Comprendre le principe de cascade du spécifique au générique.
Connaître les hiérarchies des vues courantes (single, page, archive, taxonomie, 404…).
Faire le lien thème classique (.php) et thème bloc (.html).
Cibler la bonne vue (ex. un gabarit spécifique à un CPT).

1. Le principe : de la vue demandée au fichier

À chaque requête, WordPress a déterminé quel type de vue est demandé (article seul, page, archive de catégorie, page d’auteur, recherche, 404…). Il essaie alors une liste ordonnée de noms de fichiers, du plus spécifique au plus général, et utilise le premier qui existe dans le thème.

2. Les hiérarchies des vues courantes (classique)

Vue	Cascade (simplifiée)
Article seul	`single-{post_type}-{slug}` → `single-{post_type}` → `single` → `singular` → `index`
Page	`{slug}` (`page-contact`) → `page-{id}` → `page` → `singular` → `index`
Catégorie	`category-{slug}` → `category-{id}` → `category` → `archive` → `index`
Étiquette	`tag-{slug}` → `tag-{id}` → `tag` → `archive` → `index`
Taxonomie custom	`taxonomy-{tax}-{term}` → `taxonomy-{tax}` → `taxonomy` → `archive` → `index`
Type de contenu (archive)	`archive-{post_type}` → `archive` → `index`
Auteur	`author-{nicename}` → `author-{id}` → `author` → `archive` → `index`
Recherche	`search` → `index`
404	`404` → `index`
Accueil	`front-page` → `home` → `index` (statique/blog)

Retenez la logique, pas la table : plus le nom est précis (type + slug), plus il est prioritaire ; archive et singular sont des génériques intermédiaires ; index est le dernier recours.

💡 Pour un dev React — C’est un routeur par convention de fichiers (comme le file-based routing de Next.js), mais inversé : au lieu que le nom du fichier définisse la route, c’est la route résolue (le type de vue) qui cherche le fichier le plus spécifique. single-livre.php = « rends ce composant quand la ressource est un livre » ; index.php = le catch-all universel [[...slug]].

3. Le rôle de `index.php`

index.php est le seul gabarit obligatoire d’un thème classique (avec style.css) : c’est le filet de sécurité utilisé quand aucun gabarit plus spécifique n’existe. Un thème peut donc être minimal (juste index.php) et fonctionner pour toutes les vues — puis se spécialiser en ajoutant single.php, archive.php, etc.

4. Thème bloc (FSE) : même principe, autres fichiers

Dans un thème bloc, la hiérarchie s’applique aux fichiers HTML de blocs du dossier templates/ :

Classique	Bloc (FSE)
`single.php`	`templates/single.html`
`page.php`	`templates/page.html`
`archive.php`	`templates/archive.html`
`404.php`	`templates/404.html`
`index.php`	`templates/index.html`

La cascade est identique ; seul le format des fichiers change (PHP vs HTML de blocs). templates/index.html est le filet de sécurité du thème bloc.

5. Cibler une vue précise (cas d’usage)

Un gabarit spécifique à un CPT : créez single-livre.php (ou templates/single-livre.html) → tous les « livres » l’utilisent, les autres articles gardent single.
Une page particulière : page-contact.php cible la page dont le slug est contact.
Une catégorie précise : category-actualites.php.
Un modèle de page choisi manuellement : les Template Names (classique) ou les gabarits assignables (FSE) permettent au créateur de choisir un gabarit dans l’éditeur, indépendamment de la cascade.

⚠️ Piège — Après avoir créé un single-livre.php, si le rendu ne change pas : vérifiez le nom exact du post_type (single-livre suppose un type livre), et que le fichier est bien dans le thème actif (pas le parent si vous êtes sur un enfant, Partie 6). Un mauvais slug de type = la cascade retombe silencieusement sur single.php.

✏️ Exercices

Vous voulez une mise en page différente pour la catégorie « portfolio ». Quel(s) nom(s) de fichier viser ?
Un thème ne contient que index.php. Qu’affiche-t-il pour un article, une archive, une 404 ?
Vous avez un CPT evenement et voulez un gabarit dédié pour l’affichage d’un événement seul. Quel fichier créez-vous (classique et bloc) ?

✅ Solution

category-portfolio.php (le plus spécifique), qui l’emporte sur category.php → archive.php → index.php.
La même chose partout : tout retombe sur index.php (filet universel), faute de gabarit plus spécifique.
Classique : single-evenement.php ; thème bloc : templates/single-evenement.html.

🧠 Quiz de révision

1. Comment WordPress choisit-il un gabarit ?

Par une cascade du plus spécifique au plus général ; il prend le premier fichier existant dans le thème.

2. Quel est le gabarit de dernier recours ?

index.php (ou templates/index.html en thème bloc), le seul obligatoire.

3. Quel fichier cible un article d’un CPT « livre » ?

single-livre.php (prioritaire sur single.php).

4. La hiérarchie diffère-t-elle entre thème classique et thème bloc ?

Non : même cascade, seuls les fichiers changent (.php classique vs .html de blocs dans templates/).

5. Quel fichier cible la page de slug « contact » ?

page-contact.php (prioritaire sur page.php).

Chapitre suivant : WP_Query & les requêtes de contenu.