Pré-requis pour ce tutoriel

  • Un navigateur web (Mozilla Firefox, Google Chrome, Safari au choix)
  • Un outil de développement (Coda, Dreamweaver, Aptana, Notepad++, etc.)
  • WordPress 2.8 installé sur le serveur de votre choix (local ou web)
  • Des bases dans le développement PHP et HTML

Il fût un temps…

… où développer un widget pour WordPress était une vraie galère, il faut l’admettre. Mais heureusement la version 2.8 de WordPress nous a apporté une API remarquablement performante. Bon pour ceux qui seraient largués depuis l’apparition du mot widget, sachez que les widgets sont de petites « briques » (d’où l’illustration ;) eh oui !) que vous pouvez disposer dans votre sidebar (si votre thème vous le permet). Elles sont bien souvent hautement paramétrable et vous permettent par exemple d’afficher les catégories de votre blog ou les tags (pour les widgets de bases) mais sachez qu’il est possible de faire tout et n’importe quoi avec, comme par exemple communiquer avec Twitter pour récupérer vos derniers tweets ou afficher une map Google étant donné que vous y mettez le code PHP que vous voulez !

La nouvelle API

Voici les nouveautés apportées par l’API 2.8 :

  • l’introduction de l’objet en PHP, ainsi chaque widget que vous développerez devra étendre la classe WP_Widget,
  • l’utilisation de l’AJAX pour enregistrer les préférences de vos Widgets et de vos Sidebars (fini le boutons « Enregistrer les modifications » qu’on oubliait à chaque fois !),
  • la possibilité de placer un même Widget dans plusieurs Sidebars et cela en natif (sans utilisation d’un plugin tierce),
  • et d’autres nouveautés mais qui ne nous intéresse pas ici.

Bien entendu lorsque l’on développe, quelque soit le langage où l’environnement on se retrouve confronté à la lecture d’une documentation pas toujours très claire (c’est pourquoi les tutoriels ont été inventés d’ailleurs, avoir du concret sans lire 354 pages de documentation). Toujours est-il que si vous souhaitez réellement évoluer je vous conseille de lire la documentation sur l’API Widget de WordPress au terme de ce tutoriel.

Sans plus tarder, construisons ensemble notre premier Widget.

Mon premier Widget

Je vous déconseille très fortement de vouloir développer votre Widget directement sur la version en ligne de votre blog, pour la simple et bonne raison que personne n’est exempt de faire une faute de frappe et de générer une « Parse error » PHP, et il faut avouer que ça joue sérieusement sur la crédibilité ce genre d’erreur.

Structure classique des Widgets

Dorénavant tous vos Widget devront répondre à la structure suivante :

class My_Widget extends WP_Widget {
    function My_Widget() {
       // widget actual processes
    }
    function widget($args, $instance) {
        // outputs the content of the widget
    }
    function update($new_instance, $old_instance) {
        // processes widget options to be saved
    }
    function form($instance) {
        // outputs the options form on admin
    }
}

  • My_Widget : il s’agit du constructeur de la classe, c’est dans cette méthode que sont spécifiées les informations sur la classe CSS, l’id, le titre, la description, etc.
  • widget : cette fonction sera appelée afin de procéder à l’affichage du widget dans votre sidebar
  • update : cette fonction est appelée avant la mise à jour des données, elle permet d’effectuer des vérifications sur les données saisies
  • form : cette fonction (optionnelle) a la charge d’afficher le code HTML présent dans le panneau d’administration

Widget exemple

On déclare notre classe étendant la classe WP_Widget :

function epershandFirstWidget() {
    $options = array(
        'classname' => 'eh-first-widget', // classe du widget dans la sidebar
        'description' => 'Ma description'  // la description dans l'admin
    );
    // parent::WP_Widget(identifiant, titre, options);
    parent::WP_Widget('epershand-first-widget', 'Mon premier widget', $options);
}

Lors de l’appel au constructeur père, trois paramètres sont transmis :

  • $identifiant : l’identifiant du widget, dans le code HTML de votre sidebar il sera de la forme « [identifiant]-[incrément]« , aussi je vous conseille de modifier son style en passant par la class plutôt que par l’ID,
  • $titre : le titre de votre widget dans l’interface d’administration,
  • $options : un tableau optionnel contenant :
    • classname : la classe du widget lorsqu’il sera inséré dans la sidebar, ici il s’agit de « eh-first-widget », si vous ne spécifiez par la classe alors dans ce cas elle sera de la forme « widget_[identifiant]« ,
    • description : la description du widget dans la partie admin, ici « Ma description »

   function widget($args, $instance) {
      extract($args);
      print($before_widget);
      print($before_title.$instance['title'].$after_title);
      print('Le corps de notre widget est ici'); // inséré ici ce que vous voulez
      print($after_widget);
   }

La fonction widget a la charge d’afficher le widget dans la sidebar, elle reçoit 2 paramètres :

  • $args : un tableau d’arguments passé automatiquement en paramètre, il s’agit du tableau utilisé lors de la définition du template d’une sidebar et qui spécifie le code à insérer avant le widget, avant et après le titre du widget et après le widget. Je vous conseille de garder cette base si vous souhaitez diffusez votre widget afin qu’il soit compatible avec tous les thèmes,
  • $instance : un tableau contenant toutes les variables relatives à l’instance qui doit être affichée.

   function update($new_instance, $old_instance) {
      return $new_instance;
   }

La fonction update est appelé lorsque l’utilisateur modifie les informations sur le widget via l’interface d’administration. Elle reçoit en paramètre :

  • $new_instance : un tableau associatif contenant les nouvelles valeurs des variables
  • $old_instance : un tableau associatif contenant les anciennes valeurs des variables

Ici rien de particulier n’est à noter, il suffit de retourner le paramètre $new_instance pour que les données soit mises à jour. Si toutefois vous souhaitez modifier les données vous le pouvez en modifiant directement les valeurs contenues dans le tableau $new_instance. On peut imaginer ainsi que vous effectuiez des contrôles de types ou des vérifications d’intégrité et de cohérence, libre à vous !

    function form($instance) {
        $title = esc_attr($instance['title']);
        ?>
            <p>
            	<label for="<?php echo $this->get_field_id('title'); ?>">Titre
            		<input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" />
            	</label>
            </p>
        <?php
    }

Cette fonction finalement correspond à l’affichage réalisé dans l’interface d’administration. Vous remarquerez qu’il n’y a pas de balises form, pour la simple et bonne raison que WordPress les gère tout seul. Le seul et unique paramètre est un tableau contenant les valeurs des paramètres de l’instance.

Installation du widget

C’est bien beau tout ça mais maintenant comment faire pour l’utiliser ce widget ? Pour cela plusieurs possibilités :

  • soit en passant par un plugin (qui ne contiendra que votre widget),
  • soit en passant par le fichier « fonctions.php » de votre thème et en faisant un « include » de votre widget.

La première version est nettement plus propre et pérenne puisqu’elle ne dépend pas du thème mis en place.

Activation du widget

Avant de poursuivre, je voudrais vous faire remarquer un point très important. A l’heure actuelle, votre Widget de fonctionnera pas ! Vous vous demandez sans doute pourquoi je dis ça, et bien tout simplement car nous n’avons pas informé WordPress qu’il devait traiter notre classe comme un Widget. Pour cela il faut faire appel aux « Actions » de WordPress (que je ne vais pas détailler ici mais qui fera l’objet d’un prochain tuto). Sachez juste qu’il faut ajouter la ligne suivante pour que WordPress sache quoi faire de votre classe :

add_action('widgets_init', create_function('', 'return register_widget("epershandFirstWidget");'));

Création d’un Plugin à partir du Widget

Pour créer un plugin c’est enfantin ! Il suffit d’aller dans le répertoire /wp-content/plugins et d’y ajouter un répertoire portant le nom de votre plugin, ici on va prendre « epershandFirstWidget » (vous n’êtes pas obligé de mettre le même nom que votre classe PHP).

Dans ce répertoire vous devez créer un fichier PHP portant exactement le même nom que le répertoire (et j’insiste la dessus), c’est ce fichier qui servira de point d’entrée à WordPress pour exécuter votre plugin.

En entête de votre fichier il vous faudra veiller à saisir des « méta tags » que WordPress utilisera pour afficher des informations dans l’interface d’administration. Voici un exemple :

<?php
/*
Plugin Name: Epershand First Widget
Plugin URI: http://www.epershand.net/
Description: Mon premier widget sous WordPress 2.8 avec la nouvelle API
Author: Antoine Marcadet
Version: 1.0
Author URI: http://www.antoinemarcadet.com/
*/
?>

Ensuite vous devrez activer votre plugin dans la page « Extension » (comme d’hab) et vous le verrez apparaître dans la page « Widget » (comme d’hab aussi ^^ ).

Le code complet du widget

<?php
/*
Plugin Name: Epershand First Widget
Plugin URI: http://www.epershand.net/
Description: Mon premier widget sous WordPress 2.8 avec la nouvelle API
Author: Antoine Marcadet
Version: 1.0
Author URI: http://www.antoinemarcadet.com/
*/

class epershandFirstWidget extends WP_Widget {

    function epershandFirstWidget() {
        $options = array(
            'classname' => 'eh-first-widget', // classe du widget dans la sidebar
            'description' => 'Ma description'  // la description dans l'admin
        );
        // parent::WP_Widget(identifiant, titre, options);
        parent::WP_Widget('epershand-first-widget', 'Mon premier widget', $options);
    }

    function widget($args, $instance) {
        extract($args);
        print($before_widget);
        print($before_title.$instance['title'].$after_title);
        print('Le corps de notre widget est ici'); // inséré ici ce que vous voulez
        print($after_widget);
    }

    function update($new_instance, $old_instance) {
        return $new_instance;
    }

    function form($instance) {
        $title = esc_attr($instance['title']);
        ?>
            <p>
                <label for="<?php echo $this->get_field_id('title'); ?>">Titre
                    <input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" />
                </label>
            </p>
        <?php
    }

} // class epershandFirstWidget

add_action('widgets_init', create_function('', 'return register_widget("epershandFirstWidget");'));

?>

Vers l’infini et au délà

Voilà vous connaissez les bases pour développer des Widgets avec l’API 2.8, maintenant il ne vous reste qu’à laisser libre court à votre imagination pour développer des Widgets performants et personnalisables. Je vous renvoie bien entendu à la documentation officielle de l’API Widget de WordPress.

N’hésitez pas à poser des questions ou à me corriger si vous vouyez une erreur, les commentaires sont là pour ça :)