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” :
|
1 2 3 4 5 6 7 8 9 |
<?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' ); } ?> |
Le customizer en sous-menu de Apparence
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 :
|
1 2 3 4 5 6 7 8 9 10 |
<?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
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<?php</div> <div> $wp_customize->add_section( 'my_footer', array( 'title' => __( 'Footer', 'theme' ), 'priority' => 120, ) ); </div> <div>?></div> <div> |
- 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
Section supplémentaire du customizer WordPress
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.
|
1 2 3 4 5 6 7 8 9 10 |
<?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 :
|
1 2 3 4 5 6 7 8 9 10 |
<?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
Le contrôle s’affiche maintenant dans sa section
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 :
|
1 2 3 4 5 6 7 8 9 |
<?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
Affichage de la roue des couleurs
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 :
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
<?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.
Affichage de la zone de texte créée grâce à la nouvelle classe
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 :
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
<?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
|
1 2 3 4 5 6 |
<?php</div> <div> if ( !get_theme_mod( 'my_theme_credits', false ) ) : _e('Theme by', 'ciness') ?> <a href="http://thibault-martin.fr">Thibault MARTIN</a> & <a href="http://remyperona.fr">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 :
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<?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().
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
<?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
- http://ottopress.com/2012/how-to-leverage-the-theme-customizer-in-your-own-themes/
- http://ottopress.com/2012/theme-customizer-part-deux-getting-rid-of-options-pages/
- http://ottopress.com/2012/making-a-custom-control-for-the-theme-customizer/
- http://codex.wordpress.org/Theme_Customization_API
- http://halgatewood.com/wordpress-3-4-easily-add-custom-color-pickers-to-your-theme/
Ces articles pourront vous intéresser
3 Responses to “Utiliser le customizer de WordPress dans vos thèmes !”
Trackbacks/Pingbacks
- L’Hebdo WordPress : Twenty Twelve – WordPress 3.5 – Utilisateurs | WordPress Francophone - [...] à l’option de personnalisation qui permet de changer certains éléments en quelques clics. Si vous développez un thème suivez ...
- [TUTORIAL] Use the Customizer for classipress - [...] one of the new update 3.4. display the customizer in the Appearance menu. The tutorial is here: ...
Loading ...
Ho ça déboite bien ça ! Je ne m’étais pas encore penché sur ce sujet donc je te remercie de m’avoir fait gagner ce temps précieux
Bien joué !
J’ai moi aussi utilisé le customizer dans un projet récent et comme tu le dis, la documentation est encore assez maigre (mais vues les sources de l’article, tu en as trouvé plus que moi ^^) et comme j’avais pas forcément le temps de fouiller tout le net à ce moment là, il y a quelques subtilités dont je n’étais pas au courant, comme “type” et “transport” pour
add_setting(). Merci doncÇa faisait un moment que je voulais faire un article similaire et puis… Ben voilà quoi ^^
Du coup, j’ai bien envie de faire un article qui ferait suite à celui-ci, mais sous la forme “astuces persos” plutôt, étant donné que la théorie/base est déjà là.
Pour revenir au sujet, c’est vrai que quand tu présente ça au client, ça fait son petit effet “woaw” quand même
Par contre je vois 2 inconvénients :
- un thème avec beaucoup d’options, ça me parait pas simple au final. Peut-être il serait alors nécessaire d’ajouter une page de réglages supplémentaires dans ce cas, pour les “Réglages avancés”.
- le côté multilingue me parait difficile aussi. En effet si tu veux ajouter du texte personnalisé dans le footer par exemple (en utilisant une textarea), il faut que ce texte soit traduisible, ce qui revient à avoir une textarea par langue, donc ça devient vite une usine (c’est déjà plus gérable dans une page complète de réglages)
A+
Merci !
Pour revenir sur les 2 inconvénients :
- Oui en effet, et ce n’est pas toujours justifié de l’afficher dans le customizer. C’est pourquoi j’ai quand même conservé une page d’options en supplément, pour d’autres paramètres.
- Je n’avais pas pensé à ça, mais tu as raison. Cela pourrait peut-être être géré via un un sélecteur qui affiche dynamiquement le bon champ, mais ça alourdit les choses très clairement. C’est pour ça que je pense que le customizer se limite (pour l’instant) à l’aspect graphique/présentation, et pas au contenu en lui-même.