Création d’un widget pour Wordpress

Parce qu’on ne trouve pas toujours ce dont on a besoin pour mettre en page son blog WordPress, il peut être utile de se créer soi-même ses plugins. Voici un petit tutoriel pour la création d’un widget pour WordPress.

Les bases : structure du fichier PHP

Votre plugin se créé à partir d’un fichier PHP, et plus exactement d’une classe qui étend la classe WP_Widget de l’API WordPress.
A l’intérieur de cette classe, vous devrez créer 4 fonctions :

• Le constructeur de cette classe
• La fonction d’affichage appelée widget
• La fonction de mise à jour appelée update
• La fonction d’édition du widget (affichage dans l’admin de WP) appelée form

Puis en dehors de la classe, une fonction d’initialisation appelée automatiquement par WP.

L’exemple

Prenons un exemple simple. Vous souhaitez afficher un certain nombre de posts d’une catégorie donnée. Vous allez avoir besoin de trois options dans votre widget : le titre, la catégorie, et le nombre de posts que vous souhaitez afficher.
L’API WP contient déjà certaines choses. Par exemple, lors de la création d’un widget comme celui-ci, la partie concernant le titre de votre widget est déjà gérée, et cette option s’appelle ‘title’. Vous allez devoir, par contre, créer les autres options propres à votre widget personnalisé : ici nous nous intéresserons à la catégorie (’category’) et au nombre de posts (’posts’). La suite va vous éclairer si vous ne me suivez pas tout à fait

Les fonctions

La fonction d’affichage Cette fonction va être appelée pour l'affichage du widget dans votre interface. Elle possède deux variables d'entrée : $args et $instance.$args contient les variables du widget propres à WP, et utilisée par certains thèmes pour l’affichage correct du widget. En utilisant extract($args), vous créerez ces variables, telles que $before_widget, $before_title, $after_title, et $after_widget. Ces variables seront à utiliser pour être sûr que tous les thèmes seront compatibles avec votre widget.

$instance représente le widget même, celui à afficher (depuis WP 2.8, vous pouvez utiliser plusieurs fois le même type de widget, avec un paramétrage différent, ce paramétrage sera contenu dans $instance). $instance est un tableau qui va contenir toutes les options paramétrables de votre widget (pour notre exemple, ‘title’, ‘category’ et ‘posts’). N’oubliez pas de tester si ces options ont été renseignées ou non, et d’indiquer une valeur par défaut si besoin.

Voici à quoi va ressembler la fonction :

<div class="code">

function widget($args, $instance){
    extract($args);    //on extrait les variables natives d'affichage telles que $before_widget
    $title = apply_filters('widget_title', empty($instance['title']) ? '&nbsp;' : $instance['title']); //on récupère le titre
    $category = empty($instance['category']) ? null : $instance['category']; //on récupère la catégorie à afficher
    $nb_posts = empty($instance['posts']) ? 5 : $instance['posts'] ; //on récupère le nombre de posts à afficher

    # Avant le widget - Utilisé par certains thèmes pour garantir l'uniformité d'affichage
    echo $before_widget;

    # Le titre de votre widget
    if ( $title )
        echo $before_title . $title . $after_title;

    # Le coeur du widget
    /*Insérer ce que vous désirez ici, dans notre exemple, vous allez récupérer et afficher les "$nb_posts" posts de la catégorie "$category" */

    # Après le widget
    echo $after_widget;
}
</div>

La fonction de mise à jour Cette fontion récupère 2 variables : $new_instance, $old_instance.$old_instance contient les options avant modification de votre part dans l’admin de WP.

$new_instance contient les nouvelles options, celles que vous avez modifiées, et qui vont remplacer les anciennes.Nous allons, dans cette fonction, remplacer les données de $old_instance par celles de $new_instance.

Attention, les données contenues dans les instances doivent avoir le même nom partout : pour récupérer la valeur de la catégorie dans la fonction d’affichage, nous avons utilisé $instance['category'], dans la fonction de mise à jour, nous utiliseront le même nom « category ».

<div class="code">
function update($new_instance, $old_instance)
{
    $instance = $old_instance; //on fait une copie de $old_instance, que l'on va pouvoir modifier
    //on récupère la variable 'title' dans $new_instance et on l'enregistre dans $instance
    $instance['title'] = strip_tags(stripslashes($new_instance['title']));
    //on enregistre la variable 'category'
    $instance['category'] = strip_tags(stripslashes($new_instance['category']));
    //on enregistre la variable 'posts'
    $instance['posts'] = strip_tags(stripslashes($new_instance['posts']));

    return $instance;
}
</div>

Note : strip_tags et stripslashes sont des fonctions php utilisées par sécurité, pour éviter les problèmes d’affichage.

La fonction d’édition

Cette fonction va créer le formulaire affiché dans l’admin de WP qui va vous servir à paramétrer les options. L’API de Wordpress va s’occuper de la majorité de la construction de ce formulaire, notamment pour le « bloc », et pour les boutons Enregistrer et Supprimer. Vous n’avez qu’à vous soucier des champs de saisie.Cette fonction récupère en paramètre d’entrée le widget actuel $instance. S’il s’agit d’un nouveau widget, les champs seront renseignés avec des valeurs par défaut. S’il s’agit d’un widget déjà en place que vous souhaitez modifier, les champs contiendront les valeurs actuelles des options.

La première étape va donc être de récupérer le contenu des options dans leur état actuel. Puis nous construisons les champs de saisie, qui vont permettre de modifier ces options.

function form($instance) {
    //on récupère tout d'abord les valeurs de chaque option.
    //les valeurs par défaut sont définies ici, par exemple 'posts'=>'5' défini le nombre de posts à afficher à 5 par défaut
    $instance = wp_parse_args( (array) $instance, array('title'=>'', 'category'=>'', 'posts'=>'5') );

    //on stocke les valeurs, en s'assurant qu'ils vont s'afficher correctement
    $title = htmlspecialchars($instance['title']);
    $category = htmlspecialchars($instance['category']);
    $posts = htmlspecialchars($instance['posts']);

    // On affiche les champs de saisie, avec les valeurs des options récupérées précédemment
    //Le titre tout d'abord, celui qui sera affiché sur votre blog
    echo '<label for="' . $this->get_field_name('title') . '">' . __('Title:') . '
<input style="width: 250px;" id="'.this->get_field_id('title').'" name="' . $this->get_field_name('title') . '" type="text" value="' . $title . '" /></label>';
    //La catégorie
    echo '<label for="' . $this->get_field_name('category') . '">' . __('Catégorie (name or ID):') . '
<input style="width: 200px;" id="'.$this->get_field_id('category') . '" name="' . $this->get_field_name('category') . '" type="text" value="' . $category . '" /></label>';
    //Le nombre de posts à montrer
    echo '<label for="' . $this->get_field_name('posts') . '">' . __('Nombre de posts à montrer:') . '
<input style="width: 200px;" id="'.$this->get_field_id('posts') . '" name="' . $this->get_field_name('posts') . '" type="text" value="' . $posts . '" /></label>';

}

WP va ensuite s’occuper de récupérer, les options modifiées, de les transmettre à la fonction de mise à jour lorsque vous cliquerez sur le bouton Enregistrer dans votre interface d’administration WP.

Le constructeur de la classe

Le nom de la classe doit être identique au nom du fichier PHP qui contient votre code. Si vous nommez votre fichier Widget_Affichage_Categorie.php, votre classe devra s’appeler Widget_Affichage_Categorie.Juste avant le constructeur de classe, vous devez écrire un entête, qui permettra à WP d’en savoir un peu plus sur le plugin à afficher. Il se compose du nom du plugin (Plugin Name), de la version (Version), de l’adresse où télécharger le plugin (Plugin URI), de la description du plugin (Description), de son auteur (Author), et du site de l’auteur (Author URI).

Le constructeur de la classe, ensuite, va définir certaines variables dont WP a besoin pour construire le plugin. Il ne prend aucun paramètre.

<div class="code">
/*
 * Plugin Name: Affichage d'une catégorie
 * Version: 1.0
 * Plugin URI: http://pro.pixiedaydream.fr/?p=273
 * Description: Exemple de widget permettant d'afficher une catégorie
 * Author: Pixie
 * Author URI: http://pro.pixiedaydream.fr
 */
class Widget_Affichage_Categorie extends WP_Widget  //le nom de la classe /!\
{
    function Widget_Affichage_Categorie()
    {
        //les options du widget vont être le nom de la classe (classname) et sa description
        $widget_ops = array('classname' => 'Widget_Affichage_Categorie', 'description' => __( "Permet d'afficher un certain nombre de posts d'une catégorie") );
        //les contrôles permettent de définir les dimensions du widget dans l'administration WP
        $control_ops = array('width' => 300, 'height' => 300);
        //dans la parenthèse centrale, écrivez le nom du widget qui apparaîtra dans l'admin de WP
        $this->WP_Widget('Widget_Affichage_Categorie', __('Affichage d'une catégorie'), $widget_ops, $control_ops);
    }
</div>

La fonction d’initialisation

Cette fonction se trouve en dehors de votre classe (donc après avoir fermé la dernière accolade). Elle va permettre à WP d’enregistrer votre widget comme tel. Elle doit être appelée juste après sa définition via la fonction native de WP ‘add_action’.

<div class="code">
function affichageCategorieInit() //donnez un nom qui vous parle -pas de prérequis
{
    register_widget('Widget_Affichage_Categorie'); //le nom de la classe
}
add_action('widgets_init', 'affichageCategorieInit'); //le nom de la fonction définit juste au dessus
</div>

Pour finir

Il n’y a plus qu’à assembler tout ça !Vous trouverez ici le fichier complet de cette exemple. Pour vous en servir, allez dans le répertoire wp-content/plugins/ où vous créer un dossier et où vous collerez le fichier Widget_Affichage_Categorie.php

Sources

Tutoriel de Jesse Altman