Deux clés de theme.json sont souvent confondues par les développeurs qui découvrent les thèmes blocs : customTemplates et templateParts. Toutes deux vivent au même endroit du fichier, toutes deux font référence à des fichiers HTML du thème, mais elles ne servent pas du tout au même usage. La première décrit des templates de page complets et optionnels ; la seconde décrit des fragments réutilisables et leur rôle dans la structure du site.
Sur un projet de site vitrine pour un cabinet de conseil, la confusion entre les deux nous a fait perdre une bonne heure : un template part déclaré par erreur dans customTemplates apparaissait dans le sélecteur de gabarit de page, au lieu d’être proposé comme en-tête réutilisable. Voici la distinction à retenir, avec des exemples concrets.
customTemplates : des gabarits de page en plus des gabarits standards
WordPress résout automatiquement des templates comme single.html, page.html ou archive.html à partir de leur nom de fichier, selon la hiérarchie de templates habituelle. customTemplates sert à déclarer des gabarits supplémentaires, non couverts par cette hiérarchie automatique, que l’auteur ou l’autrice de contenu peut choisir manuellement depuis le panneau de réglages de page.
{
"customTemplates": [
{
"name": "pleine-largeur",
"title": "Page pleine largeur",
"postTypes": [ "page" ]
},
{
"name": "landing-campagne",
"title": "Landing page campagne",
"postTypes": [ "page", "evenement" ]
}
]
}Chaque entrée pointe implicitement vers un fichier du même nom dans le dossier templates/ du thème — ici templates/pleine-largeur.html. Le champ postTypes restreint la proposition de ce gabarit aux types de contenus listés : sans lui, le template serait proposé pour tous les types de contenus publics, ce qui n’a pas toujours de sens.
templateParts : associer un fichier à une zone du site
templateParts répond à un besoin différent : indiquer à l’éditeur de site à quelle zone structurelle correspond un fragment de template. WordPress prédéfinit trois zones : header, footer, et uncategorized pour tout le reste.
{
"templateParts": [
{
"name": "header",
"title": "En-tête",
"area": "header"
},
{
"name": "footer",
"title": "Pied de page",
"area": "footer"
},
{
"name": "barre-annonce",
"title": "Barre d'annonce",
"area": "uncategorized"
}
]
}
Pourquoi la zone change le comportement dans l’éditeur
La valeur de area n’est pas qu’une étiquette décorative : elle conditionne la façon dont le template part est traité par l’éditeur de site. Un template part déclaré en zone header ou footer bénéficie d’un affichage dédié dans l’inserteur, regroupé sous ces libellés, et peut être proposé automatiquement comme point d’insertion en haut ou en bas d’un nouveau template. Un template part en zone uncategorized reste disponible dans l’inserteur, mais sans ce traitement privilégié — il apparaît simplement comme un fragment générique parmi d’autres.
| Zone | Effet dans l’éditeur |
|---|---|
| header | Regroupement dédié, proposition automatique en haut de template |
| footer | Regroupement dédié, proposition automatique en bas de template |
| uncategorized | Fragment générique, aucun placement automatique |
Sur le projet du cabinet de conseil, nous avons ainsi déclaré une barre d’annonce en zone uncategorized plutôt que header : elle devait pouvoir être insérée librement à différents endroits selon les templates, sans hériter du comportement automatique réservé à l’en-tête principal.
Ce que ces clés ne font pas
Un point mérite d’être clarifié : ni customTemplates ni templateParts ne créent le moindre fichier. Ces clés décrivent des fichiers HTML qui doivent déjà exister dans les dossiers templates/ et parts/ du thème. Déclarer une entrée sans fichier correspondant ne provoque pas d’erreur bloquante, mais aboutit à un gabarit proposé dans l’interface qui, une fois sélectionné, ne produit aucun rendu utile. La création concrète de ces fichiers HTML de template, leur structure interne en blocs, relève d’un autre sujet et n’est pas traitée ici.
Bonnes pratiques de nommage
- Utiliser des noms de fichiers explicites en anglais technique ou en français cohérent avec le reste du thème, jamais un mélange des deux.
- Toujours renseigner un
titlelisible : c’est ce libellé, et non le nom de fichier, qui s’affiche dans l’éditeur. - Limiter
postTypesaux types de contenus réellement concernés, pour éviter de polluer le sélecteur de gabarit sur des contenus où ce template n’a pas de sens.
En résumé
Retenez la distinction de fond : customTemplates propose des gabarits de page optionnels à la personne qui rédige, tandis que templateParts indique à l’éditeur de site le rôle structurel d’un fragment de template. Les deux clés se contentent de décrire des fichiers existants ; elles ne remplacent en rien le travail de création des templates eux-mêmes.
