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
<?php
$wp_customize->add_section( ‘my_footer’, array(
‘title’ => __( ‘Footer’, ‘theme’ ),
‘priority’ => 120,
)
);
?>
- 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
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.
<?php
$wp_customize->add_setting( 'my_theme_credits', array( 'default' => false, 'capability' => 'edit_theme_options', 'transport' => 'postMessage' ) );
?>
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)
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 :
<?php
$wp_customize->add_control( 'my_theme_credits', array( 'settings' => 'my_theme_credits', 'label' => __( "Hide theme's credits", 'ciness' ), 'section' => 'my_theme_footer', 'type' => 'checkbox', ) );
?>
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 :
<?php
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array( 'label' => __( 'Link color', 'theme'), 'section' => 'colors', 'settings' => 'link_color', ) ) );
?>
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';
public function render_content() { ?> <label> <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span> <textarea rows="5" style="width:100%;" <?php $this->link(); ?>><?php echo esc_textarea( $this->value() ); ?></textarea> </label> <?php } }
$wp_customize->add_control( new RP_Customize_Textarea_Control( $wp_customize, 'my_theme_intro_content', array( 'label' => __( 'Front page introduction content', 'ciness' ), 'section' => 'static_front_page', 'settings' => 'my_theme_intro_content' ) ) );
?>
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 :
<?php
$colors = array();
$colors[] = array( 'slug' => 'wrap_bg', 'default' => '#FFFFFF', 'label' => __('Content background', 'ciness' ) );
// on répète cela pour chaque réglage de couleur
foreach ( $colors as $color ) { $wp_customize->add_setting( $color['slug'], array( 'default' => $color['default'], 'capability' => 'edit_theme_options', 'transport' => 'postMessage' ) );
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, $color['slug'], array( 'label' => $color['label'], 'section' => 'colors', 'settings' => $color['slug'], ) ) ); }
?>
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
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
<?php
if ( !get_theme_mod( 'my_theme_credits', false ) ) : _e('Theme by', 'ciness') ?> <a href="http://thibault-martin.fr">Thibault MARTIN</a> & <a href="https://remyperona.ca">Rémy PERONA</a> <?php endif; ?>
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 :
<?php
add_action( 'wp_head', 'my_theme_output_custom_css' ); function my_theme_output_custom_css() { $inline_css = ' <!--Customizer CSS--> <style> .wrap { background:' . get_theme_mod( 'wrap_bg', '#FFFFFF' ) . '; } </style> <!--/Customizer CSS-->'; echo $inline_css; }
?>
Etape 7 : activer l’affichage en temps réel
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