# Thème hybride : ajouter theme.json et des templates blocs à un thème classique

> Adopter progressivement theme.json, block-templates/ et les template parts dans un thème classique existant, sans migration totale ni réécriture complète.

- Auteur : Clément Hadrot
- Publié le : 2022-05-13
- Mis à jour le : 2022-05-13
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/theme-hybride-theme-json-templates-blocs/

## L’essentiel

- theme.json coexiste avec un functions.php classique
- block-templates/ ne remplace que certains gabarits
- Migration réversible, page par page

Le site de l'association Les Mains Tendues reposait sur un thème classique robuste, avec un Customizer complet et des gabarits PHP éprouvés depuis des années. Une migration complète vers un thème à blocs aurait représenté un chantier disproportionné par rapport au budget disponible. La solution retenue a consisté à transformer le thème existant en thème hybride : un thème classique qui adopte progressivement `theme.json` et quelques templates blocs, sans abandonner ses gabarits PHP existants.

WordPress permet cette coexistence depuis que `theme.json` et les dossiers `block-templates/` et `block-template-parts/` peuvent être ajoutés à un thème classique sans que celui-ci ne devienne un thème à blocs complet. Ce tutoriel montre comment procéder sans tout casser.

## Ajouter theme.json sans renoncer au Customizer

Première étape : créer un fichier `theme.json` minimal à la racine du thème, qui ne définit que les réglages liés à l'éditeur de blocs — palette de couleurs, tailles de police — sans toucher aux options déjà gérées par le Customizer :

```
{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"color": {
			"palette": [
				{ "slug": "primaire", "color": "#1f4b3f", "name": "Vert associatif" },
				{ "slug": "accent", "color": "#d98c31", "name": "Ocre" }
			]
		},
		"typography": {
			"fontSizes": [
				{ "slug": "normal", "size": "18px", "name": "Texte courant" },
				{ "slug": "grand", "size": "28px", "name": "Titre de section" }
			]
		}
	}
}
```

Dès l'ajout de ce fichier, les déclarations équivalentes en PHP — `add_theme_support( 'editor-color-palette' )`, `add_theme_support( 'editor-font-sizes' )` — deviennent redondantes et doivent être retirées de `functions.php` pour éviter toute confusion sur la source de vérité. Le reste du Customizer, logo, menus, widgets, continue de fonctionner exactement comme avant.

## Introduire des templates blocs sur des gabarits ciblés

> L'essentiel à retenir : theme.json coexiste avec un functions.php classique ; block-templates/ ne remplace que certains gabarits ; Migration réversible, page par page

La présence de `theme.json` autorise l'ajout d'un dossier `block-templates/`, contenant des fichiers HTML qui peuvent remplacer certains gabarits PHP, sans obligation de tout convertir d'un coup. Sur ce projet, seule la page « Faire un don », très évolutive et régulièrement modifiée par l'équipe de communication, a été convertie en template bloc :

```
<!-- block-templates/page-don.html -->
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
	<!-- wp:post-title /-->
	<!-- wp:post-content /-->
</main>
<!-- /wp:group -->

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

WordPress résout ce fichier grâce à son nom, selon une logique proche de la hiérarchie de templates classique : `page-don.html` s'applique à la page dont le slug est `don`, exactement comme `page-don.php` l'aurait fait dans un thème purement classique. Toutes les autres pages du site continuent de passer par `page.php`, resté intact.

## Réutiliser l'en-tête et le pied de page existants comme template parts

Pour que le template bloc de la page de don affiche le même en-tête et le même pied de page que le reste du site, ces deux zones ont dû être extraites dans des template parts HTML, situés dans `block-template-parts/`. Le contenu de ces fichiers reprend la structure visuelle de `header.php` et `footer.php`, traduite en blocs, mais les fichiers PHP d'origine restent en place pour toutes les pages qui n'utilisent pas encore de template bloc.

### Ce qui coexiste sans conflit, et ce qui demande de la rigueur

- Les widgets d'un thème classique restent fonctionnels tant qu'aucune zone de widgets n'a été convertie en zone de blocs globale.
- Le Customizer continue de piloter le logo et les menus, indépendamment de theme.json.
- En revanche, il faut éviter que deux sources différentes (un réglage Customizer et une valeur theme.json) définissent la même chose, sous peine d'un comportement imprévisible selon le contexte d'affichage.

> Un thème hybride n'est pas une solution bâclée : c'est une façon responsable d'introduire l'éditeur de site là où il apporte une vraie valeur, sans sacrifier un thème classique qui fonctionne déjà correctement par ailleurs.

## Pour aller plus loin

Cette approche progressive a permis à l'association de gagner en autonomie éditoriale sur sa page la plus stratégique, sans budget de refonte complète. La migration totale vers un thème à blocs, si elle devient un jour nécessaire, se fera page par page à partir de cette base déjà partiellement convertie, plutôt que d'un seul bloc risqué.