Comment créer un thème enfant WordPress

Pour créer un thème enfant WordPress, ajoutez un nouveau dossier dans wp-content/themes, placez-y un fichier style.css dont l’en-tête Template correspond au nom du dossier du thème parent, puis activez-le. Le thème enfant hérite des modèles, des styles et des fonctionnalités du parent et ne contient que vos modifications.

Si vous avez déjà modifié directement les fichiers d’un thème avant de voir la mise à jour suivante tout effacer, le thème enfant est la solution pour éviter cela.

Ce guide présente la configuration adaptée au WordPress moderne. Il détaille la création d’un thème enfant classique avec un chargement correct des feuilles de style, la surcharge des modèles et des fonctions, ce qui change pour les thèmes basés sur les blocs comme Twenty Twenty-Four, ainsi que les cas où un thème enfant n’est pas nécessaire.

Pourquoi modifier directement un thème parent est-il voué à l’échec ?

Lors de la mise à jour d’un thème, WordPress remplace ses fichiers par la nouvelle version : toute modification effectuée dans le dossier du thème est donc perdue. Un thème enfant conserve vos changements dans un dossier distinct que les mises à jour ne touchent jamais. Le guide des thèmes enfants du Theme Handbook le présente comme le moyen de bénéficier des mises à jour du parent sans renoncer à vos propres modifications. Le système de thèmes se limite à deux niveaux, un parent et un enfant : vous ne pouvez donc pas installer un thème « petit-enfant » par-dessus.

Comment créer un thème enfant dans WordPress (thèmes classiques)

Un thème enfant classique nécessite un dossier, un fichier style.css doté d’un en-tête Template et, dans la plupart des cas, un fichier functions.php qui met en file d’attente la feuille de style. L’organisation reprend la structure dossier, style.css et functions.php décrite dans notre guide sur la création d’un thème WordPress responsive avec Bootstrap. La différence, c’est que l’enfant ne contient que ce qu’il modifie.

wp-content/themes/
├── twentytwentyfour/
└── tt4-child/
    ├── style.css
    └── functions.php

L’en-tête de style.css

Seul style.css est strictement obligatoire. La documentation sur la feuille de style principale indique que tout thème doit comporter au minimum un en-tête Theme Name, auquel un thème enfant ajoute Template.

/*
 * Theme Name:  TT4 Child
 * Template:    twentytwentyfour
 * Version:     1.0.0
 * Text Domain: tt4-child
 */

Template prend comme valeur le nom du dossier du parent, et non son nom d’affichage. Si les deux ne correspondent pas caractère pour caractère, WordPress ne reliera pas l’enfant à son parent.

Mettre en file d’attente les feuilles de style plutôt qu’utiliser @import

Chargez les styles du thème enfant avec wp_enqueue_style() sur le hook wp_enqueue_scripts, et non avec @import. De nombreux tutoriels anciens chargent les styles du parent via un @import en tête du style.css de l’enfant. Cette approche est obsolète :

/* Outdated: do not use */
@import url("../twentytwentyfour/style.css");

Le navigateur ne découvre le fichier importé qu’après avoir téléchargé et analysé la feuille de style de l’enfant : les deux requêtes s’enchaînent donc l’une après l’autre et bloquent toutes deux le rendu. L’import échappe en outre au système de mise en file d’attente de WordPress, qui ne peut alors ni gérer ses dépendances, ni le versionner, ni éviter les doublons.

La solution de remplacement consiste à appeler wp_enqueue_style() depuis une fonction accrochée à wp_enqueue_scripts. Ce même hook sert aussi à charger les scripts, comme l’explique notre article sur l’ajout de JavaScript personnalisé aux thèmes WordPress.

<?php
// functions.php
add_action( 'wp_enqueue_scripts', 'tt4child_enqueue_styles' );

function tt4child_enqueue_styles() {
	wp_enqueue_style(
		'tt4child-style',
		get_stylesheet_uri(), // the active (child) theme's style.css
		array(),              // $deps: handles that must load first
		'1.0.0'               // $ver: appended as a cache-busting query string
	);
}

Le code de mise en file d’attente adapté à un thème enfant dépend de ce que le thème parent charge déjà :

Pour le troisième cas, utilisez ceci :

function tt4child_enqueue_styles() {
	wp_enqueue_style(
		'tt4child-parent-style',
		get_parent_theme_file_uri( 'style.css' )
	);
}

Pour savoir quel cas s’applique, recherchez wp_enqueue_style dans le functions.php du parent, ou repérez les balises <link> de feuilles de style dans le code source de la page. L’ordre des feuilles de style n’est pas figé : il suit les appels de mise en file d’attente, et l’argument $deps accepte un tableau d’identifiants (handles) enregistrés qui doivent être chargés en premier. Pour que la feuille de l’enfant soit insérée après celle du parent, passez l’identifiant du parent dans $deps, en le relevant dans le code du parent. Lorsque l’URL de la feuille de style de l’enfant est erronée, la requête renvoie une erreur 404 et la page s’affiche avec le seul CSS du parent. Un outil de relecture de session (session replay) qui enregistre les requêtes réseau en parallèle de la restitution visuelle affiche la requête en échec à côté de la page dépourvue de styles.

Comment surcharger les modèles du parent ?

Pour surcharger un modèle du parent, copiez le fichier (ne le déplacez pas) vers le même chemin relatif dans le thème enfant. Lorsque WordPress parcourt la hiérarchie des modèles, il vérifie le dossier de l’enfant avant celui du parent : un fichier portant le même nom dans l’enfant est donc utilisé en priorité. Déplacer le fichier au lieu de le copier modifie le thème parent, et la mise à jour suivante le remettra de toute façon en place.

twentytwentyfour/page.php  →  copy to  →  tt4-child/page.php

La même règle s’applique aux parties de modèle. Vous pouvez également ajouter de nouveaux modèles absents du parent.

Surcharger les fonctions du parent

Le fichier functions.php d’un thème enfant ne remplace pas celui du parent. Selon le Handbook, WordPress exécute les deux fichiers, en commençant par celui de l’enfant et en enchaînant directement avec celui du parent. Cet ordre de chargement a deux conséquences. Les fonctions du parent encapsulées dans function_exists() (fonctions dites « pluggables ») peuvent être redéfinies dans l’enfant. Toute autre fonction du parent doit être décrochée ou complétée. Ne copiez pas non plus le code du functions.php du parent dans celui de l’enfant : déclarer deux fois les mêmes noms de fonctions interrompt le site avec une erreur fatale.

Une fonction pluggable dans le parent se présente ainsi :

// Parent theme
if ( ! function_exists( 'parenttheme_credit' ) ) {
	function parenttheme_credit() { /* ... */ }
}

Comme l’enfant s’exécute en premier, définir le même nom dans l’enfant fait que la version du parent est ignorée :

// Child theme
function parenttheme_credit() {
	echo '<p>Custom credit line</p>';
}

Si la fonction n’est pas pluggable, supprimez-la avec remove_action(), en utilisant le même hook et la même priorité que lors de son enregistrement. Un appel à remove_action() placé au premier niveau du fichier de l’enfant s’exécute avant que le parent n’ait ajouté son hook : il n’y a donc encore rien à supprimer. Exécutez-le depuis after_setup_theme, qui se déclenche une fois les fichiers functions.php des deux thèmes chargés :

// Parent theme
add_action( 'init', 'parenttheme_setup_extra', 20 );

// Child theme
add_action( 'after_setup_theme', function () {
	remove_action( 'init', 'parenttheme_setup_extra', 20 );
} );

remove_filter() fonctionne de la même manière pour les filtres. Pour compléter une fonction du parent plutôt que la remplacer, accrochez votre propre fonction au même hook avec une priorité plus tardive. La priorité par défaut de add_action() est 10, et les valeurs plus élevées s’exécutent plus tard :

add_action( 'parent_footer', 'tt4child_footer_extra', 20 );

Comment fonctionnent les thèmes enfants pour les thèmes basés sur les blocs ?

Un thème enfant de thème basé sur les blocs, par exemple construit sur Twenty Twenty-Four, n’a souvent besoin que de style.css et de theme.json. Les styles étant principalement définis dans theme.json, le Handbook précise que la mise en file d’attente de style.css est souvent superflue, et de nombreux thèmes enfants de ce type n’ont aucun fichier functions.php.

tt4-child/
├── style.css
├── theme.json
├── templates/
│   └── single.html
├── parts/
│   └── header.html
└── patterns/
    └── (same filename as the parent pattern).php

Pour surcharger un modèle, une partie de modèle ou une composition, ajoutez un fichier portant le même nom. Pour les compositions, l’en-tête Slug enregistré doit également correspondre à celui du parent : copiez-le donc depuis le fichier du parent :

<?php
/**
 * Title: Footer
 * Slug: parent-slug/pattern-name
 */
?>

Un theme.json minimal fixe le schéma et utilise la version 3, qui nécessite WordPress 6.6 ou ultérieur :

{
	"$schema": "https://schemas.wp.org/wp/6.6/theme.json",
	"version": 3,
	"styles": {
		"typography": {
			"lineHeight": "1.7"
		}
	}
}

Les fichiers theme.json du parent et de l’enfant sont fusionnés selon des règles précises, les valeurs de l’enfant étant prioritaires. Les personnalisations enregistrées dans l’Éditeur de site sont par ailleurs stockées en base de données et se situent au-dessus du thème enfant dans le modèle de couches du Handbook. Si un modèle de l’enfant semble ignoré, effacez la personnalisation enregistrée pour ce modèle dans l’Éditeur de site.

Quand un thème enfant n’est pas nécessaire

Pour de petits ajustements visuels ou des fonctionnalités, un thème enfant n’est pas nécessaire. Sur un thème classique, le CSS additionnel de l’outil de personnalisation suffit pour quelques règles. Avec un thème basé sur les blocs, le CSS personnalisé passe plutôt par le panneau Styles de l’Éditeur de site. Les modifications fonctionnelles, comme les types de contenu personnalisés, relèvent d’une extension, afin de continuer à fonctionner après un changement de thème. Si vos modifications deviennent si importantes que le thème enfant devient difficile à maintenir, le Handbook suggère de créer un fork du parent pour en faire votre propre thème.

Conclusion

Un thème enfant se résume à un dossier et à un fichier style.css dont la valeur Template correspond au nom du dossier du parent. Sur les thèmes classiques, ajoutez un code de mise en file d’attente adapté à ce que charge le parent. Sur les thèmes basés sur les blocs, theme.json et des fichiers de modèle portant le même nom font le travail. Commencez par vérifier quelles feuilles de style votre parent met en file d’attente, puis n’ajoutez que les fichiers que vous devez réellement modifier.

FAQ

Quelle est la différence entre get_template_directory_uri() et get_stylesheet_directory_uri() dans un thème enfant ?

Lorsqu'un thème enfant est actif, get_template_directory_uri() renvoie l'URL du dossier du thème parent, tandis que get_stylesheet_directory_uri() renvoie l'URL du dossier du thème enfant. Utilisez la variante stylesheet pour les fichiers stockés dans l'enfant. Depuis WordPress 4.7, get_theme_file_uri() est souvent le meilleur choix : elle renvoie la copie du fichier présente dans l'enfant si elle existe, et se rabat sur le fichier du parent dans le cas contraire.

Pourquoi mes réglages de l'outil de personnalisation et mes emplacements de menu ont-ils disparu après l'activation d'un thème enfant ?

WordPress stocke les réglages de l'outil de personnalisation (theme mods) séparément pour chaque thème, en les associant au nom du dossier du thème actif : un thème enfant démarre donc avec son propre jeu de réglages vide et n'hérite pas de ceux du parent. Vos menus existent toujours, mais vous devez les réaffecter aux emplacements de menu et ressaisir ou importer les autres réglages. Les réglages du parent restent en base de données et réapparaissent si vous revenez au thème parent.

Qu'advient-il d'un fichier de modèle copié dans un thème enfant lorsque le thème parent est mis à jour ?

La copie de l'enfant reste exactement telle que vous l'avez enregistrée, et WordPress continue de l'utiliser à la place du fichier mis à jour du parent. Les corrections de bugs, correctifs de sécurité ou modifications de balisage apportés par le parent à ce fichier n'atteignent jamais votre surcharge. Après chaque mise à jour du parent, comparez vos fichiers surchargés avec les nouvelles versions du parent et intégrez ce dont vous avez besoin. Surchargez le moins de fichiers possible pour que cela reste gérable.

Peut-on créer un thème enfant pour un thème basé sur les blocs sans écrire de code ?

Oui. L'extension officielle Create Block Theme, disponible sur WordPress.org, propose une option Create Child Theme. Elle génère un enfant du thème basé sur les blocs actif, comme Twenty Twenty-Four, et inscrit dans les fichiers de l'enfant les modifications effectuées dans l'Éditeur de site. L'extension est conçue pour les thèmes basés sur les blocs : un enfant d'un parent classique nécessite donc toujours la configuration style.css et functions.php décrite ci-dessus.