Créer un simple widget WordPress

Dans ce premier tutoriel-vidéo de notre série « widgets WordPress », nous allons étudier la technique officielle pour créer un widget personnalisé WordPress de toute pièce. Le widget créé permettra de lister des statistiques d’un compte YouTube, à savoir le nombre de vidéos envoyées par l’utilisateur et la durée totale de ces vidéos.

Plongez dans ce tutoriel-vidéo pour vous familiariser avec la technique officielle de création d’un widget.

• Codex WordPress sur l’API des widgets : codex.wordpress.org
• Code créé dans ce tutoriel : http://pastebin.com/mC20AF2c

Que l’on soit créateur de thèmes WordPress publics ou développeur de site WordPress pour clients, il est souvent nécessaire d’étendre l’éventail de widgets à disposition dans WordPress. Lister des posts de nouveaux types de contenu, afficher les derniers tweets, ajouter un formulaire d’inscription à une mailing-list… les possibilités sont infinies !

Certes, des plugins existent pour 99% de ces nécessités, pourquoi s’embêter ? Si vous avez un peu de temps et aimez savoir comment fonctionne le moteur WordPress, alors vous êtes au bon endroit : découvrons le code derrière la création d’un widget WordPress.

L’extension de la classe WP_Widget

Le coeur WordPress définit une classe nous permettant d’ajouter des « objets widgets ». La création d’un widget personnalisé se résume donc à étendre cette classe native et y définir :

1. des configurations globales (nom & description affichés dans l’admin, ID du widget, largeur…) à travers la méthode __construct()
2. la création du formulaire de réglages du widget dans l’administration avec form()
3. le traitement des données enregistrées en back-end avec update() si vous désirez filtrez / vérifiez les valeurs enregistrées par l’utilisateur dans le formulaire de réglages du widget
4. la partie front-end traitant les données du formulaire et affichant les infos du widget sur votre site avec widget()
   
5. (et hors de notre sous-classe, l’enregistrement avec register_widget pour offrir notre nouveau widget dans l’administration WordPress)

Tout ça réuni, la structure de l’ajout d’un widget ressemble à ça :

class YouTube_Simple_Stats extends WP_Widget {

  // Configuration globale du widget
  function __construct() {
    $widget_args = array(
      'classname' => 'widget_yt_simple_stats',
      'description' => 'Affiche un rapide résumé d'un profil d'utilisateur YouTube'
    );

    $control_args = array(
      'width' => 450
    );

    parent::__construct(
      'yt_simple_stats',
      __('Statistiques simples YouTube'),
      $widget_args,
      $control_args
    );
  }

  // Affichage en front-end
  function widget($args, $instance) {
    ...
  }

  // Traitement des données avant sauvegarde
  function update( $new_instance, $old_instance ) {
    ...
  }

  // Affichage du formulaire de réglages du widget en back-end
  function form($instance) {
    ...
  }
}

function init_youtube_widget() {
  register_widget('YouTube_Simple_Stats');
}
add_action('widgets_init', 'init_youtube_widget');

La construction du widget __construct()

On utilise la méthode de construction du parent (parent::__construct() de classe WP_Widget) en  y passant plusieurs paramètres :

1. l’identifiant (ID) du widget qui sera utilisé comme identifiant CSS du widget
2. le titre/nom qui s’affichera dans l’intitulé du bloc d’administration représentant le widget dans Widgets disponibles
3. une array $widget_args de réglages propres au widget contenant la classe CSS (classname) et la description dans le bloc du widget dans l’administration (description)
4. une array $control_args de réglages du formulaire d’administration du widget comme la largeur de ce dernier (on aborde ça en détaille dans cet article)

Le traitement des données du formulaire de réglages update()

Vous remarquez 2 variables disponibles dans cette méthode : $new_instance et $old_instance. Cette méthode est utilisée lorsque l’utilisateur clique sur le bouton « Enregistrer » du formulaire de réglages du widget : si vous le désirez, vous avez la possibilité de filtrer/modifier les nouvelles valeurs ($new_instance) voire même les ignorer (dans ce cas, utilisez la seconde variable $old_instance).

Le formulaire de réglages form()

En relation avec update() que l’on vient de décrire, form() est la fonction qui génèrera l’apparence du formulaire de réglages du widget dans l’administration WordPress. Utilisez wp_parse_args($instance) pour définir des valeurs par défaut sur certaines configurations si vous en ressentez le besoin.

Vous pouvez y écrire n’importe quel code HTML valide, formulaire ou non, afin de générer l’affichage des réglages du widget ou une description par exemple.

L’affichage du widget sur votre site widget()

Le premier argument $args contient des informations précieuses concernant la sidebar ET le widget en question. En utilisant extract($args), on aura ensuite accès à des variables comme :

1. $before_widget et $after_widget pour afficher le HTML wrapper qui entoure votre widget, défini dans votre thème avec register_sidebar
2. $before_title et $after_title pour afficher le HTML wrapper qui entoure le titre du widget, également défini dans register_sidebar

Le second argument $instance met à votre disposition les variables relatives à ce widget et stockées dans la base de données. Par exemple, si vous avez défini un champ username dans le formulaire du widget (décrit plus bas), vous aurez accès à la valeur définie par l’utilisateur à travers $instance[‘username’].

L’enregistrement du widget register_widget()

Enfin, une fois le comportement de notre nouveau widget défini, on utilise register_widget à l’intérieur du hook-action widgets_init d’initialisation des widgets dans l’admin WordPress. Ainsi, notre nouveau widget apparait dans l’administration du site et peut-être glisser-déposer dans une sidebar pour accéder à sa configuration.

Et voila, un nouveau widget créé ! Une technique assez méthodique et pas très évidente à retenir mais l’effort investi en vaut le coup. Dans notre prochain tutoriel de cette série, nous étudierons l’utilisation d’une librairie-helper qui facilite grandement la création de widgets et qui s’avère nettement plus compréhensible et lisible que la version officielle…

Suivez-moi sur Twitter pour découvrir la suite !