Le blog.

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.


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.

Profitez des méthodes $this->get_field_id et $this->get_field_name pour générer automatiquement les attributs HTML « id » et « name » de vos input dans le formulaire de réglages.

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
$before/after_widget/title sont accessibles dans l'affichage front-end du widget
$before/after_widget/title sont accessibles dans l’affichage front-end du widget

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 !

18 commentaires ont été rédigés, ajoutez le votre.

  1. xtrembaker Répondre

    Merci pour ce tutoriel ! Toutefois je rencontre un pb, le widget créé n’apparait pas dans la console d’administration -> Apparence -> widgets ..

    Où dois-je placer le fichier widget_youtube_stats.php ? Est-ce que WordPress est censé « auto-charger » la classe ou bien dois-je la déclarer quelque part ? Pour info j’utilise la version 3.8.0 de wordpress.

    Merci par avance !

    • Pierre Saïkali Répondre

      Heureux que ça vous plaise !

      Ce fichier est évidemment à inclure dans votre thème/plugin avec une fonction comme …
      require_once locate_template(‘widget_youtube_stats.php’);

      • Pierre Saïkali Répondre

        Cette fonction à mettre dans functions.php de votre thème par exemple…

  2. X-Raym Répondre

    Super tuto, très clair et détaille :)
    Merci !

  3. hayat Répondre

    salam
    merci pour le tuto , bien structuré

  4. phidias Répondre

    Très bon tuto, mais ça aurait été sympa de mettre ton éditeur de texte en plein écran, j’avais les yeux qui piquaient à la fin de la vidéo… :)

  5. phidias Répondre

    Re, après quelques tentatives infructueuses et quelques modifs, mon widget a fini par apparaitre dans les extensions avec la possibilité de l’activer et de le placer dans la barre des widgets mais il ne fonctionne pas. (je crois car l’aside contenant les widgets a disparu et surtout ça me déglingue toute l’apparence du thème)
    Ma question:Je pense que le problème vient de ces 3 lignes qui utilisent visiblement une librairie ou un template Zend(je sais pas trop en fait)
    set_include_path(get_template_directory() . ‘/inc/ZendGData’);
    require_once ‘Zend/Loader.php’;
    Zend_Loader::loadClass(‘Zend_Gdata_YouTube’);
    Y’a t-il un moyen de contourner ce problème svp???
    Merci d’avance.

    • Pierre Saïkali Répondre

      Si tu mets WP_DEBUG à TRUE dans wp-config.php, tu devrais avoir plus d’info. Tu me diras !

  6. Lythande Répondre

    Zend est un framework ? Il faut le télécharger j’imagine ?

  7. rider22 Répondre

    J’ai bien peur que le résultat soit le même… :(
    Et aucune notification d’erreur nulle part.

  8. phidias Répondre

    Hélas le résultat est le même… :(
    Aucune notification d’erreur n’apparaît nulle part

  9. phidias Répondre

    Petite précision supplémentaire, j’ai téléchargé la librairie ZendGdata que j’ai placé de la sorte sur un petit site en local pour faire mes bidouilles avant de le placer sur mon site qui est déjà en ligne:
    C:\wamp\www\wordpress\wp-content\themes\fortunato\inc

  10. phidias Répondre

    Bon, visiblement après quelques recherches il s’avère que la librairie ZendGdata soit deprecated.
    Pour info, je suis en ce moment en formation de développeur et ça m’aurait été bien utile face au jury d’avoir réussi la création de ce widget.
    Aurais-tu une idée pour arriver au même résultat en tentant une autre approche ???
    Merci beaucoup d’avance.

  11. Marion Répondre

    Bonjour, ce tutoriel à l’air vraiment bien, mais quand je fais le simple test d’inscrire les lignes suivantes pour voir comment ça s’affiche, c’est simple, je n’ai plus rien qui s’affiche, ni le back office, ni le front office (je suis obligée de supprimer le fichier pour pouvoir retrouver mon wordpress) :

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

    > Pourtant, tout les tuto de création de widget commencent par ça… Comment ça se fait que ça ne fonctionne pas chez moi, une idée ?

  12. Marion Répondre

    Autant pour moi, je me suis emmêlée les pinceaux, j’ai tout recommencé avec la vidéo ci-dessus, et le résultat est beaucoup plus convainquant, merci.

    Par contre, j’aurais besoin d’un petit coup de main concernant l’enregistrement des cases à cocher. Dans cet exemple il n’y a que des champs de texte, mais j’ai besoin d’une checkbox, et je ne sais pas quel terme utiliser pour le get_filed et/ou le checked/unchecked, est-ce que vous avez une idée de ce que je dois remplir pour que cette case soit prise en compte ?

  13. Marion Répondre

    Elle est où la prochaine vidéo sur les widgets, avec worprdess widget helper class svp ?

  14. Eric Répondre

    Bonjour,
    J’ai un problème avec les widget !
    Il faut que je met le code de la widget dans le fichier functions.php sinon le widget ne s’affiche pas dans le panneau.
    Tant dis que je veux mettre le code widget dans un fichier a part.

    Une solution a ca ?

Laisser un commentaire