Utiliser la personnalisation de WordPress dans vos thèmes !

Personnalisation thème WordPressLe 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' );
 }
?>
Sous-menu personnaliser

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) :
<?php

$wp_customize->add_section( ‘my_footer’, array(
‘title’ => __( ‘Footer’, ‘theme’ ),
‘priority’ => 120,
)
);

?>
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.
Section supplémentaire Personnalisation

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)
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 :

<?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

Contrôle personnalisation

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 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 :

<?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.

Classe personnalisée textarea

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
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 :
<?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

Leave a comment

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.

ante. luctus suscipit Sed risus. Donec amet, dictum consequat. id,