Configurer un thème WordPress avec le fichier theme.json

Les blocs de Gutenberg offrent de nombreuses options de personnalisation, dont la configuration globale et les styles se déclarent dans un fichier theme.json, situé à la racine de votre thème WordPress.

Largeur des contenus, choix des couleurs, des polices de caractères, des espacements, des bordures… L’apparence générale du thème ainsi que celle de chacun des blocs peuvent être définies dans ce fichier. Il permet d’assurer une uniformité visuelle du site et d’éviter d’avoir un site arc-en-ciel et illisible.

La structure du fichier theme.json

Depuis la version 5.8 de WordPress il est possible de configurer quasiment tous les réglages d’un thème basés sur les blocs Gutenberg via le fichier theme.json. Cela facilite la création de thèmes pour les développeurs. Le fichier theme.json est découpé en plusieurs sections dans lesquelles vous pouvez définir les réglages de base de votre thème et des différents blocs Gutenberg.

{
    "version": 2,
    "settings": { ... },
    "styles": { ... },
    "customTemplates": { ... },
    "templateParts": { ... },
    "patterns": { ... }
}

La section "settings" du fichier theme.json

La section "settings" permet d’activer ou de désactiver certaines options de personnalisation du thème et des blocs Gutenberg.

{
    "version": 2,
    "settings": {
        "appearanceTools": false,
        "border": { ... },
        "color": { ... },
        "custom": { ... },
        "dimensions": { ... },
        "layout": { ... },
        "spacing": { ... },
        "typography": { ... },
        "blocks": { ... }
    },
    "styles": { ... },
    "customTemplates": { ... },
    "templateParts": { ... },
    "patterns": { ... }
}

Dans la section "settings", vous pouvez notamment configurer :

• L’activation de certains paramètres par défaut comme la gestion des bordures, des espacements, des hauteurs de lignes pour les textes via l’argument "appearanceTools".
• L’ajout de bordures et les options à activer pour celles-ci (couleur, taille, style et arrondi) grâce à l’argument "border".
• La palette des couleurs disponibles pour personnaliser les différents blocs (couleurs simples et gradients), ainsi que les options d’affichage de ces couleurs (textes, fonds etc.) à travers l’argument "color". Vous pouvez également choisir de conserver les couleurs par défaut de Gutenberg et l’ajout de couleurs personnalisées.
• Des propriétés personnalisées à l’intérieur de l’argument "custom", comme des épaisseurs de police de caractères par exemple.
• La possibilité de définir des dimensions aux différents éléments du site, comme la hauteur minimum d’un élément, via l’argument "dimensions".
• Les différentes largeurs des contenus prises en charge par le thème avec l’argument "layout".
• Les espacements par défaut comme les marges internes et externes des blocs ou le choix des espaces entre les colonnes à travers l’argument "spacing".
• Les options des polices de caractères du thème avec l’argument "typography" (choix de tailles personnalisées, polices de caractères à charger etc).
• Les options à afficher pour chacun des blocs Gutenberg en les appelant dans l’argument "blocks". Par exemple, vous pouvez décider qu’un utilisateur ne puisse ajouter que des marges externes sur le bloc Titre, même si les marges internes sont activées pour les autres blocs.

En bref, la section "settings" permet de définir un cadre concernant les personnalisations possibles des différents éléments de votre thème depuis l’interface d’administration du site.

La sections "styles" du fichier theme.json

La section "styles" contient les valeurs par défaut des réglages d’un thème.

{
    "version": 2,
    "settings": { ... },
    "styles": {
        "border": { ... },
        "color": { ... },
        "dimensions": { ... },
        "filter": { ... },
        "spacing": { ... },
        "typography": { ... },
        "elements": { ... },
        "blocks": { ... }
    },
    "customTemplates": { ... },
    "templateParts": { ... },
    "patterns": { ... }
}

Autrement dit, elle permet aux développeurs de définir le style global du thème. Ainsi, les contributeurs pourront ajouter des blocs dans leurs contenus sans forcément avoir à personnaliser systématiquement leur apparence. Bien configurer la section "style" du fichier theme.json est primordial si vous souhaitez apporter de la cohérence et une uniformité visuelle à votre thème.

La section "customTemplates" du fichier theme.json

La section "customTemplates" est apparue depuis la version 5.9 de WordPress. Comme son nom l’indique, elle sert à déclarer l’existence de templates particuliers pour certains types de posts (pages, articles, ou type de post personnalisé). Ces templates seront placés dans un répertoire "templates" situé à la racine de votre thème.

{
    "version": 2,
    "settings": { ... },
    "styles": { ... },
    "customTemplates": [ 
        {
            "name": "my-custom-template",
            "title": "The template title",
            "postTypes": [
                "page",
                "post",
                "custom-post-type"
            ]
        }
    ],
    "templateParts": { ... },
    "patterns": { ... }
}

Pour fonctionner, chaque déclaration de template doit contenir :

• Le nom du template.
• Le titre du template.
• Les types de posts utilisant le template (par défaut, les templates déclarés ne s’appliquent qu’aux pages).

La section "templateParts" du fichier theme.json

Dans l’article sur la création d’un thème WordPress basé sur les blocs de Gutenberg, nous expliquions l’intérêt de créer des templates parts pour les éléments globaux de votre thème (barre de navigation / pied-de-page). Depuis la version 5.9 de WordPress, vous pouvez établir des zonings dans votre thème afin d’y intégrer vos templates parts et de les rendre personnalisables depuis l’interface d’administration du site.

{
    "version": 2,
    "settings": { ... },
    "styles": { ... },
    "customTemplates": { ... },
    "templateParts": [
        {
            "name": "header",
            "title": "Header",
            "area": "header"
        },
        {
            "name": "footer",
            "title": "Footer",
            "area": "footer"
        }
    ],
    "patterns": { ... }
}

La section "patterns" du fichier theme.json

La dernière section du fichier theme.json est la section "patterns", ajoutée depuis la version 6.0 de WordPress. Elle permet de déclarer de façon simplifiée les différentes compositions auxquelles les contributeurs du site pourront avoir accès depuis l’éditeur. Pour cela, il suffit d’indiquer le slug de chacun des patterns que vous aurez développés.

{
    "version": 2,
    "settings": { ... },
    "styles": { ... },
    "customTemplates": { ... },
    "templateParts": { ... },
    "patterns": [
        "slug-du-premier-pattern",
        "slug-du-deuxième-pattern",
        "slug-du-troisième-pattern",
        "etc."
    ]
}

En conclusion, l’utilisation du fichier theme.json pour configurer votre thème WordPress n’est pas obligatoire. Toutefois, elle peut s’avérer très utile pour définir son apparence générale et les possibilités de personnalisation de celui-ci.