# customTemplates et templateParts dans theme.json : déclarer ses gabarits

> Ce que font vraiment les clés customTemplates et templateParts de theme.json, comment elles organisent les zones du site, et leur effet dans l'éditeur.

- Auteur : Clément Hadrot
- Publié le : 2023-07-31
- Mis à jour le : 2023-07-31
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/customtemplates-templateparts-theme-json/

## L’essentiel

- customTemplates déclare des gabarits additionnels proposés dans l'éditeur
- templateParts associe un fichier à une zone (header, footer…)
- Ces clés décrivent des templates existants, elles ne les créent pas

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"
    }
  ]
}
```

> L'essentiel à retenir : customTemplates déclare des gabarits additionnels proposés dans l'éditeur ; templateParts associe un fichier à une zone (header, footer…) ; Ces clés décrivent des templates existants, elles ne les créent pas

## 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 `title` lisible : c'est ce libellé, et non le nom de fichier, qui s'affiche dans l'éditeur.
- Limiter `postTypes` aux 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.