Le customizer de WordPress a été une des nouveautés de la mise à jour 3.4. Celui-ci permet aux développeurs de thèmes de proposer à leurs utilisateurs une interface pratique pour personnaliser les différents éléments d’apparence du site, tout cela en temps réel depuis l’administration. La documentation sur le support de cette fonctionnalité étant assez éparse, je vous propose aujourd’hui un tutoriel basé sur mon intégration du customizer au dernier thème que j’ai réalisé.
En tout premier lieu, toutes les fonctions qui vont suivre devront être ajoutées au fichier functions.php de votre thème, ou dans un fichier externe qui sera intégré via un include/require.
Etape 1 : afficher le customizer dans le menu Apparence
Par défaut, le customizer est caché dans le sous-menu “Thèmes” du menu “Apparence”, avec un bête lien “Personnaliser”. Afin de rendre cela plus accessible, nous allons créer un sous-menu “Personnaliser” du menu “Apparence” :
<?php add_action ('admin_menu', 'my_customizer_admin');
function my_customizer_admin() {
// ajouter le lien du customizer au menu Apparence
add_theme_page( __( 'Customize theme', 'theme' ), __( 'Customize Theme', 'theme' ), 'edit_theme_options', 'customize.php' );
}
?>
Etape 2 : créer la fonction et l’ajouter au hook
Nous allons ensuite créer la fonction qui s’occupe d’intégrer des réglages supplémentaires au customizer, et l’ajouter au hook correspondant :
<?php
add_action( 'customize_register', 'rp_customize_register' );
function my_theme_customize_register($wp_customize) {
// on mettra ici tous les réglages supplémentaires
}
?>
Etape 3 : ajouter une section
Les réglages du système de personnalisation sont divisés en section. Il en existe un certain nombre par défaut, qui s’afficheront si leurs fonctionnalités correspondantes sont actives sur le thème :
title_tagline – Titre et description du site
colors – Couleurs
header_image – Image d’en-tête
background_image – Image d’arrière-plan
nav – Menus de navigation
static_front_page – Page d’accueil
Mais il est possible d’en rajouter si on en a besoin. J’ai par exemple ajouté une section “Pied de page” (le code est à placer dans la fonction de l’étape 2) :
add_section() prend 2 arguments, le 1er est l’identifiant que l’on donne à la nouvelle section (qui sera utilisé par la suite), et le second un tableau comprenant :
title : le titre de la section
description (si on le souhaite) : sera ajouté en attribut “title” du titre
priority : détermine à quel endroit dans la liste des sections elle s’affichera
Nous voici donc avec une section supplémentaire.
Etape 4 : ajouter les settings
Un setting est un élément qui pourra être utilisé dans votre thème. Grâce à la fonction add_setting(), WordPress s’occupera de lui même de créer, récupérer ou modifier l’élément. On va créer ici un setting qui permet de gérer l’affichage des crédits du thème.
add_setting() prend également 2 arguments de la même façon. Le 1er correspond à son identifiant, le second à un tableau de 4 paramètres :
default : une valeur par défaut si nécessaire
type : permet de déterminer de quelle façon est sauvegardé le réglage (option ou theme_mod)
capability : les permissions nécessaires pour qu’un utilisateur puisse modifier ce réglage
transport (optionnel) : postMessage permet d’activer la mise à jour en temps réel, au lieu de recharger la page (valeur par défaut refresh)
Notre réglage est enregistré, mais pour pouvoir l’utiliser il est nécessaire d’y ajouter un contrôle.
Etape 5 : ajouter les contrôles
Un contrôle va être un élément de formulaire qui va s’afficher et permettre la modification des réglages. Il en existe de plusieurs types, tels que “text”, “select”, “checkbox”, “radio” qui correspondent aux éléments classiques. Mais également des personnalisés comme “dropdown-pages” qui crée une liste déroulante des pages du site, ou encore un autre qui permet l’utilisation d’une roue de couleurs pour la sélection.
Prenons un exemple avec une checkbox pour mon réglage d’affichage des crédits du thème :
Toujours pareil, 2 paramètres pour add_control(), l’identifiant puis un tableau de 4 paramètres :
settings : correspond à l’identifiant créé auparavant avec add_setting
label : le label du champ de formulaire
section : la section à laquelle on rattache cet élément de réglage
type : le type de champ
Etape 4-5 bis : configuration avancée
Roue de couleurs
Je vous ai donné un exemple pour créer un contrôle avec un des types par défaut, mais il est possible d’aller plus loin. Comme je l’ai dit il existe une méthode pour afficher une roue de couleurs, mais cela diffère un peu :
Nous créons ici une instance de la classe WP_Customize_Color_Control, et qui permet l’affichage de la roue. Cette classe étend la classe WP_Customize_Control, celle qui s’occupe de l’affichage des contrôles. WP_Customize_Color_Control prend 3 paramètres :
$wp_customize, obligatoire
un identifiant pour le contrôle
un tableau de paramètres équivalent aux contrôles par défaut
Contrôle personnalisé
Il est également possible de créer des contrôles personnalisés, pour ajouter de nouveaux éléments. Par exemple la zone de texte (textarea) n’est pas disponible par défaut, mais on peut la créer. Il faut tout d’abord créer une nouvelle classe, qui va étendre WP_Customize_Control, puis créer le contrôle qui l’utilise :
<?php
class RP_Customize_Textarea_Control extends WP_Customize_Control {
public $type = 'textarea';
On y définit le type, et la fonction render_content() sert à créer le rendu HTML. Dans le contrôle, on fait comme d’habitude, en créant une instance de la classe nouvelle créée.
Factorisation du code
Si vous ajoutez plusieurs réglages du même type dans la même section, il peut être une bonne idée de factoriser tout cela pour rendre votre code plus clair et plus efficace. Par exemple, je propose de nombreux réglages de couleurs dans mon thème, qui se trouvent tous dans la section “Couleurs” et utilisent tous la roue. Il est donc possible de factoriser de cette façon :
Tout d’abord nous créons un tableau nommé $colors, qui permettra de stocker les paramètres de chaque élément. Nous y ajoutons ensuite des valeurs :
slug : l’identifant qui sera utilisé où nécessaire dans add_setting() et add_control
default : pour la valeur par défaut dans add_setting
label : pour le label dans add_control
Et nous passons ce tableau dans une boucle foreach qui va créer un à un les contrôles en récupérant les valeurs stockées.
Etape 6 : afficher les modifications dans le thème
Pour afficher les modifications faites dans le thème, il est nécessaire de récupérer la valeur enregistrée dans la base de données. Cela se fait grâce à la fonction get_theme_mod(), qui prend 2 paramètres :
l’identifiant du réglage
une valeur par défaut
Pour l’affichage des crédits de mon thème, on l’utilisera de la manière suivante :
my_theme_credits peut avoir comme valeur TRUE ou FALSE (car c’est une checkbox). Si sa valeur est TRUE, on masque le texte, sinon, on l’affiche. La valeur par défaut est FALSE.
Si vous souhaitez faire des modifications sur l’apparence avec CSS, il vous faudra créer une fonction qui va injecter les styles dans le head de votre site, grâce au hook wp_head. Voici un exemple :
Pour activer l’affichage des modifications en temps réel, nous allons ici encore créer une fonction qui va s’appuyer sur jQuery pour faire les modifications, et l’injecter avec le hook wp_footer. Pour rappel, il est nécessaire d’avoir définit la valeur “postMessage” à “transport” dans la fonction add_setting().
<?php
if ( $wp_customize->is_preview() && ! is_admin() ) // la fonction est ajoutée uniquement pour le customizer
add_action( 'wp_footer', 'rp_customize_preview', 21);
function rp_customize_preview() {
?>
<script type="text/javascript">
( function( $ ){
wp.customize('wrap_bg',function( value ) {
value.bind(function(to) {
$('.wrap').css('background', to ? to : '' );
});
});
}
?>
wp.customizer prend l’identifiant du réglage en paramètre. On définit ensuite la cible (ici la classe “wrap”) et la modification voulue (définir la valeur de background à “to” qui est la variable contenant la valeur hexadécimale de la couleur ici).
Cela doit être reproduit pour chaque réglage en temps réel voulu, et toutes les méthodes de jQuery sont utilisables.
Conclusion
Vous êtes maintenant en mesure de mettre en œuvre le customizer sur vos propres thèmes. Cela requiert un peu de temps avant d’en maitriser toutes les facettes, mais c’est un élément extrêmement pratique, et surtout intégré à WordPress par défaut. Il vient évidemment en réponse aux outils de personnalisation intégrés aux thèmes premium notamment, mais il permet une standardisation qui à mon avis est bénéfique à la fois pour les développeurs et les utilisateurs.
Alors, allez-vous l’utiliser dans vos prochains thèmes ?
Ressources utilisées pour la création de cet article
