# Précédence des template parts entre thème enfant et parent bloc

> Un thème enfant dont le header.html n'est jamais chargé : règles précises de résolution entre parent et enfant pour les gabarits d'un thème bloc.

- Auteur : Clément Hadrot
- Publié le : 2023-07-04
- Mis à jour le : 2023-07-04
- Catégorie : FSE
- URL : https://wpmoderne.dev.wordpress-developpement.fr/fse/precedence-template-parts-theme-enfant-parent-bloc/

## L’essentiel

- Le support du thème enfant reste expérimental via le plugin Gutenberg
- La résolution se fait dossier par dossier, jamais globalement
- Un fichier bien placé suffit, sans configuration PHP

« Mon thème enfant ne charge jamais mon `header.html`, c'est toujours celui du parent qui s'affiche. » Ce message, reçu d'un développeur travaillant sur un thème enfant de thème bloc, illustre une confusion fréquente au sujet d'une fonctionnalité encore en cours de stabilisation à cette date, actuellement disponible via le plugin Gutenberg et dont l'arrivée complète dans le cœur de WordPress est annoncée pour la prochaine version majeure.

Contrairement à l'héritage bien connu des thèmes enfants PHP classiques, où un simple fichier du même nom dans le thème enfant suffit à remplacer celui du parent, le mécanisme équivalent pour les thèmes blocs impose une organisation précise du dossier, sans quoi rien ne se passe comme attendu.

## Ce que la résolution vérifie précisément

Pour qu'un fichier de template part du thème enfant remplace effectivement celui du parent, il doit se trouver exactement au même chemin relatif dans le dossier `parts` du thème enfant que celui utilisé par le thème parent, avec un nom de fichier strictement identique. Une différence de casse, un sous-dossier supplémentaire, ou un chemin légèrement différent suffit à faire échouer silencieusement le remplacement.

Sur ce projet précis, le thème parent rangeait son fichier dans `parts/header.html`, mais le développeur du thème enfant avait placé le sien dans `parts/site-header.html`, en pensant, à tort, qu'un nom de fichier différent mais explicite suffirait à être reconnu comme un remplacement intentionnel du header. Ce n'est absolument pas le cas : le mécanisme repose entièrement sur l'identité exacte du chemin et du nom de fichier.

## Le correctif appliqué

```
# Structure attendue pour que le remplacement fonctionne correctement
mon-theme-parent/
  parts/
    header.html
    footer.html

mon-theme-enfant/
  style.css          (avec Template: mon-theme-parent)
  parts/
    header.html      (même nom, même emplacement relatif)
```

> L'essentiel à retenir : Le support du thème enfant reste expérimental via le plugin Gutenberg ; La résolution se fait dossier par dossier, jamais globalement ; Un fichier bien placé suffit, sans configuration PHP

Une fois le fichier renommé et déplacé au bon emplacement, exactement `parts/header.html` dans le thème enfant, le remplacement a fonctionné immédiatement, sans configuration PHP supplémentaire ni déclaration explicite dans un fichier de fonctions. Cette simplicité, une fois le bon chemin identifié, contraste avec la difficulté initiale à comprendre pourquoi rien ne se passait.

## Ce qui distingue ce mécanisme de l'héritage PHP classique

- Aucune fonction équivalente à `get_stylesheet_directory()` n'a besoin d'être appelée manuellement : la résolution est entièrement gérée par le cœur du système de thèmes blocs.
- Le principe de résolution s'applique de la même façon aux fichiers de `templates` et de `parts`, avec la même exigence de chemin identique entre parent et enfant.
- Le fichier `theme.json` suit une logique différente : il peut être partiellement complété par l'enfant, sans obligation de dupliquer l'intégralité du fichier parent, contrairement aux templates et template parts qui fonctionnent en tout ou rien.

## Une vérification rapide à connaître

Pour confirmer qu'un remplacement fonctionne réellement, la méthode la plus fiable reste d'ajouter temporairement un commentaire HTML visible, comme `<!-- version enfant -->`, dans le fichier suspecté, puis de vérifier sa présence dans le code source de la page affichée. Cette méthode rustique évite bien des suppositions erronées sur ce qui est réellement chargé.

> Un mécanisme d'héritage, aussi élégant soit-il sur le papier, ne vaut que par la rigueur de son application. Un chemin de fichier approximatif suffit à le rendre totalement inopérant.

## En résumé

Cette règle de précédence stricte, bien que déroutante au premier abord pour qui connaît l'héritage plus permissif des thèmes PHP classiques, reste finalement simple une fois comprise : même chemin, même nom, rien de plus. Je recommande de toujours vérifier cette structure de dossiers en tout premier lieu, avant d'envisager une cause plus complexe à un remplacement de template part qui ne fonctionne pas comme attendu.