Formation « Créer un site WordPress avec le Full Site Editing »

Full Site Editing : Présentation du theme.json

Lecture : 8 minutes • 7

Le theme.json est le fichier le plus important des thèmes modernes WordPress, car c’est via celui-ci que l’on va configurer notre design system dans l’éditeur, à savoir les couleurs, polices, espacements… Il va également nous permettre d’activer ou désactiver des fonctionnalités de l’éditeur, et définir les styles par défaut du site.

La création d’un site avec le Full Site Editing commence avec le theme.json, du moins pour les développeurs et les low-codeurs.

Ce fichier vous permet de déclarer un bon nombre d’informations comme les couleurs, espacements, tailles, typos… à propos de votre thème à l’aide de clés et valeurs.

On retrouve en substance tous les réglages que l’on peut faire via l’éditeur de site.

Voici un exemple avec le réglage de largeur des contenus. Depuis l’éditeur cela ressemble à ceci :

Panneau de configuration des largeurs de contenus du site dans le Full Site Editing.
Les réglages de largeur dans l’éditeur de site

Et dans le theme.json, ça ressemble plutôt à cela :

JSON
theme.json

Mais en réalité, il va bien plus loin que l’interface visuelle, il permet notamment d’activer ou désactiver certaines fonctionnalités de l’éditeur. Et ça, on ne peut pas le faire autrement qu’en modifiant le fichier theme.json.

En tant que développeurs, on va donc privilégier cette approche. On pourra ainsi versionner toutes nos configurations avec git.

Aparté: Le format JSON

Le format JSON est un des formats de données les plus en vogue du moment. C’est d’ailleurs le format de référence des API REST.

Il fonctionne par clés / valeurs et contrairement à un objet JavasScript, il faut que chaque clé soit entre guillemets. Exemple : "clé" : "valeur".

Les valeurs de type numériques ou booléennes n’ont quant à elles pas besoin de guillemets. Exemple : "fontWeight" : 500 ou "defaultPalette" : true.

Pensez à la virgule en fin de ligne, à part si vous êtes sur la dernière instruction. Et voilà, vous savez faire du JSON !

Anatomie du theme.json

Si vous prenez un thème tout fait (comme Ollie ou le thème par défaut de WP) et que vous ouvrez le fichier theme.json, vous pourriez vous faire une petite frayeur devant parfois plus de 1000 lignes.

Mais ne vous inquiétez pas, on va découper et se concentrer sur un concept à la fois dans chacun des cours de ce chapitre.

Et on va d’abord commencer par comprendre la structure globale de ce fichier :

JSON
theme.json

Si je me cantonne uniquement aux éléments de premier niveau, on obtient ceci :

  • $schema : C’est la nomenclature qui contraint les valeurs possibles du fichier ;
  • version : Le numéro de version du schéma ;
  • settings : Ici on va définir nos valeurs globales et les fonctionnalités de l’éditeur ;
  • styles : Pour appliquer nos styles par défaut aux titres, textes, et blocs ;
  • customTemplates : Pour déclarer des modèles sur-mesure en plus des existants ;
  • templateParts : Nous permet de déclarer l’en-tête, le pied de page et la sidebar ;
  • patterns : Ajouter des compositions du répertoire officiel de WordPress.

On va profiter de ce cours pour aller un peu plus dans les détails.

Pour connaître l’intégralité des possibilités offertes par le theme.json, vous pouvez vous référer à la documentation officielle :

Documentation officielle du theme.json

Des nouveautés sont ajoutées à chaque nouvelle version de WordPress. Ça bouge encore beaucoup de ce côté là, alors n’hésitez pas à consulter la documentation régulièrement pour ne rien rater.

Conseil

Prenez de l’inspiration en jetant un œil au theme.json du thème Ollie ou du thème par défaut de WordPress afin de voir ce qu’il est possible de faire.

Les différentes sections du theme.json

Allez, maintenant on va aller voir ce qu’il se passe dans chacune des sections du theme.json.

Ce sera bien plus facile de modifier ce fichier des enfers une fois que vous aurez retenu à quoi sert chaque section.

Car pour ne rien arranger, on retrouvera souvent des sous-sections portant des noms similaires à d’autres endroits du fichier. Du coup, les premiers temps seront un peu difficiles, mais ne vous inquiétez pas, vous serez très bientôt un expert.

Le schéma de standardisation et la version

On commence avec le schéma. On va systématiquement le mettre dans notre fichier car ça permettra à notre éditeur de code de vérifier que ce que l’on écrira par la suite sera conforme à ce schéma.

JSON
theme.json

Si ce n’est pas le cas, votre éditeur vous le signalera. Par exemple, j’ai tenté d’ajouter la clé core dans mon fichier, et VS Code me souligne la ligne qui ne lui convient pas :

capture du thème.json dans VS Code. la ligne indiquant le terme core est soulignée car invalide.
La clé « core » est soulignée car elle n’existe pas dans le schéma

De cette manière, vous saurez immédiatement si ce que vous ajoutez à votre theme.json est valide ou non.

De plus, votre éditeur sera capable de vous suggérer les valeurs possibles lors de l’écriture du fichier. C’est encore plus pratique pour ne pas se tromper :

VS Code suggère les valeurs possibles à insérer dans la section Typography du theme.json.
La suggestion des propriétés du theme.json

Dans cet exemple, VS Code me suggère les valeurs possibles à l’intérieur de Settings > Typography.

Attention

N’écoutez pas les suggestions de l’IA quand vous éditez ce fichier, car bien souvent, elles sont « dévinées » et donc fausses. Fiez-vous uniquement aux valeurs suggérées par VS Code, via le schéma.

Bien sûr, le schéma va évoluer avec le temps. WordPress proposera des nouveautés, mais aussi des changements structurels. C’est pour cela que vous allez également indiquer le numéro de version du schéma à suivre.

À l’heure où j’écris ces lignes, on est à la version 3. Pensez à consulter la documentation du theme.json à chaque début de projet pour connaître la version la plus récente.

Vous pouvez également consulter la documentation du schema actuel sur wordpress.org.

Settings

Cette partie est probablement la plus importante de ce theme.json, car c’est ici qu’on va configurer les 2 choses les plus importantes pour notre site :

  • Les styles globaux tout d’abord : couleurs, typographies, espacements…
  • Mais également les fonctionnalités à activer ou désactiver dans Gutenberg.

Voici un exemple concernant les couleurs :

JSON
theme.json

Comme vous pouvez le voir, sous color on va avoir des instructions booléennes permettant d’activer ou de désactiver les options de couleur dans l’éditeur Gutenberg.

Ensuite, on déclare la liste des couleurs de la palette que l’on va proposer sur le site.

Voici ce que ça donnera dans l’éditeur de WordPress :

Le sélecteur de couleurs de WordPress sous deux déclinaisons : à gauche avec pleins d'options, et à droite seulement la palette.
Le sélecteur de couleurs avec et sans fonctionnalités

À gauche, c’est si je passe toutes les valeurs à true, et à droite, si je passe tout à false. C’est un bel exemple du contrôle qu’on peut avoir sur Gutenberg, n’est-ce pas ?

Dans les prochains cours, on passera en revue tous les réglages disponibles afin de bien comprendre l’objectif de chaque valeur.

Conseil

Cette partie settings permet à la fois : l’interprétation de votre design system en terme de valeurs globales, mais vous donne également le contrôle sur les contraintes de l’éditeur Gutenberg, afin d’assurer la meilleure UX possible à vos clients.

Styles

Les éléments de notre charte graphique que nous avons configurés dans settings seront disponibles dans l’éditeur.

Mais on va également pouvoir appliquer ces styles globalement aux différents éléments du site grâce à la section styles du fichier JSON.

Voici à quoi ça ressemble :

JSON
theme.json

Chaque section permet de définir un élément bien précis :

  • color : Les couleurs des textes, liens, du fond ;
  • spacing : L’espacement par défaut entre les blocs, et dans les blocs ;
  • typography : La police des titres et celle des textes ;
  • elements : Les styles des éléments primitifs : boutons, niveaux de titres, survol ;
  • blocks : Les styles par défaut à appliquer pour chaque bloc de l’éditeur.

Les valeurs qu’on a définies précédemment sont désormais disponibles au travers de variables CSS, avec des noms parfois un peu longs.

Voici un exemple avec les couleurs globales du site :

JSON
theme.json

Dans cet exemple, on applique notre couleur primaire à tous les textes, et la couleur blanche sur le fond du site. Ce ne sera donc pas nécessaire de le faire en CSS.

Si on veut maintenant définir une couleur spécifique à la balise <h2>, ce sera dans elements > h2 > color.

Vous allez voir que c’est une sacré gymnastique au début de trouver le bon endroit pour définir les styles d’un élément. Mais pas d’inquiétude, on y reviendra dans les prochains cours.

Nommage des valeurs globales CSS dans le theme.json

Revenons pour le moment sur les valeurs globales. Leur nom est un peu long, et un peu indigeste au début, je ne vous le cache pas. Mais on prend vite l’habitude, promis !

Voici l’anatomie d’une valeur générée par wordPress :

Le schéma représente le nommage des valeurs globales de WordPress, sous forme de type, propriété et valeur, séparés par des |
Le nommage des valeurs globales dans le theme.json

Décortiquons ce nommage bien singulier :

  1. La première partie var: indique qu’on souhaite utiliser une valeur globale ;
  2. La seconde partie est le type, il peut-être preset ou custom ;
  3. La troisième représente la propriété : color, font-size, spacing
  4. Et la dernière partie représente la valeur configurée en JSON : primary, s, m

Je n’entre pas encore dans les détails, on abordera le sujet dans un cours séparé. Pour le moment, l’objectif est que vous commenciez à prendre vos repères dans ce fichier theme.json.

Conseil

Pour bien comprendre : dans Settings on définissait les valeurs possibles (couleurs, espacements…) de notre charte graphique, et dans styles on va appliquer ces valeurs globalement sur des éléments.

Custom templates

Désormais, les modèles de page sur-mesure devront être déclarés dans le theme.json, sous la section customTemplates :

JSON
theme.json

Un exemple récurrent est de créer un modèle de page en pleine largeur, sans le titre principal, pour créer toutes vos landing pages du site.

Le modèle de page « standard » pourra être réservé aux pages de contenus comme les mentions légales, avec le titre et une zone de contenu étroite.

Avant, on déclarait les modèles directement en PHP, mais ce n’est plus valable comme nos modèles sont désormais en HTML.

Templates parts

Les template parts sont des morceaux de template, destinés à être réutilisés sur le site. Mais outre l’en-tête, le pied de page et éventuellement une sidebar, on va plutôt désormais utiliser les compositions.

JSON
theme.json

Donc en général, cette partie du theme.json ne va pas trop changer.

Patterns

Et enfin, cette section permet de déclarer les compositions que l’on veut récupérer depuis wp.org.

En effet, il existe un répertoire de compositions créées par la communauté, un peu comme le répertoire des extensions.

Le répertoire officiel des compositions de la communauté sur le site wordpress.org
Le répertoire officiel des compositions sur le site wordpress.org

Il suffit de récupérer le slug de chaque composition depuis l’URL et de les ajouter à votre fichier JSON :

JSON
theme.json

Il sera plus judicieux de créer les vôtre. On verra plus tard dans la formation comment désactiver les suggestions de compositions depuis l’éditeur.

Configuration via l’éditeur de WordPress et export

L’éditeur de WordPress permet de gérer visuellement la plupart de ces réglages. Vous pourriez donc, au lieu d’écrire le JSON passer par l’interface du Full Site Editing :

L'éditeur de style du FSE montre l'aperçu du site en temps réel ainsi qu'un volet à droite permettant de modifier les couleurs, la typographie et d'autres paramètres.
L’interface de gestion des styles dans WordPress

Ensuite, il vous suffira d’exporter votre thème, car WordPress propose justement une option pour cela.

Cliquez sur les 3 points en haut à droite de l’interface et choisissez « Exportation ».

Dans Gutenberg, à droite, on peut exporter notre thème ainsi que toutes ses configurations grâce au menu Exportation.
Exporter la configuration de son thème via le menu de Gutenberg

Cela aura pour effet de générer un zip contenant votre thème personnalisé. Vous pourrez ainsi récupérer le theme.json, mais aussi les compositions et modèles de pages en HTML !

Aparté: Comment c’est enregistré en base ?

Les réglages que vous faites depuis l’éditeur sont enregistrés en base de données dans la table wp_posts, sous forme d’un objet JSON sérialisé, dans un Custom Post Type privé wp_global_styles spécialement prévu pour les données du FSE.

D’un point de vue purement développeur, il y a moyen que vous ne trouviez pas ça fou. C’est pas dingue, mais ça fonctionne bien au final.

Lorsque vous faites un thème sur mesure, les données du JSON sont chargées par défaut, mais si elles sont surchargées, ce sont les données de la base qui feront foi.

On reparlera de cette problématique vers la fin de la formation.

Les limites de l’éditeur visuel

Par contre, en utilisant l’éditeur, vous n’aurez pas autant de possibilités qu’en modifiant le JSON. Il manque notamment :

  • L’activation et la désactivation de réglages et de fonctionnalités de l’éditeur.
  • La gestion des espacements.
  • La gestion de valeurs personnalisées, comme les arrondis.

Il y a quelques temps, il manquait la gestion des ombres, mais elle a été ajoutée avec l’arrivée de WordPress 6.6.

Dans un futur proche, il ne manquera probablement plus rien. Mais pour le moment, on est encore obligé de passer par le theme.json.


Maintenant que vous connaissez les bases du fichier theme.json, on va aller explorer les possibilités afin de trouver les plus intéressantes pour concevoir efficacement nos sites.

Dans le prochain cours, on va explorer les fonctionnalités que l’on peut activer et désactiver dans Gutenberg.

7

Questions, réponses et commentaires

  1. Mathieu Godard

    Le 2 décembre 2024

    Salut ! Le numéro de version est-il lié au changement de version de WordPress ? J’aurais tendance à dire oui mais j’aimerais être sûr. Merci 🙂

    1. Maxime BJ

      Le 2 décembre 2024

      Non c’est un versionnement à part entière lié au fichier et à ses propriétés : en cas de changement de structure, il y aura un changement de version pour que WordPress sache comment interpréter ton fichier.

      1. Mathieu Godard

        Le 7 décembre 2024

        Pardon pour le manque de précision, je parlais de la version du schéma : sans pour autant être le même numéro que la version de WordPress, est-il incrémenté à chaque nouvelle version majeure de WordPress (6.6, 6.7, …) ?

        1. Maxime BJ

          Le 7 décembre 2024

          Oui moi aussi. C’est le numéro de version du schéma. Tant que la structure ne change pas fondamentalement, on sera en version 3. De nouvelles propriétés pourront être ajoutées en version 3. Par contre, s’il y a un changement de clés ou de structure, on passera en version 4.

          1. Mathieu Godard

            Le 18 décembre 2024

            1. Maxime BJ

              Le 18 décembre 2024

              Je rajoute le lien dans le cours, merci !

          2. Mathieu Godard

            Le 7 décembre 2024

            Merci pour ta réactivité 🙂

Laisser un commentaire