• 15 hours
  • Easy

Free online content available in this course.

Paperback available in this course

course.header.alt.is_certifying

You can get support and mentoring from a private teacher via videoconference on this course.

Got it!

Last updated on 3/13/18

Créer des widgets

Log in or subscribe for free to enjoy all this course has to offer!

Comme nous avons pu le voir au début du cours, les widgets sont des éléments de base bien pratiques de l'interface graphique. Ils permettent de déplacer des blocs de fonctionnalités sur différentes zones de vos pages, mais pour être utilisables, encore faut-il en avoir défini le comportement dans le code auparavant !

Déclarer un widget

Commençons tout de suite par le widget à afficher sur le site pour l’inscription des emails.

Une nouvelle classe

Tous les widgets sont des objets qui doivent hériter de la classe WP_Widget (déclarée dans le fichier wp-includes/widgets.php) et surcharger au moins deux méthodes.

Avant tout, le constructeur de la classe WP_Widget doit être appelé par le constructeur de la classe fille afin de définir :

  • un identifiant pour le widget ;

  • un titre à afficher dans l’administration ;

  • éventuellement des paramètres supplémentaires comme la description du widget (elle aussi affichée dans le panneau « widget » de l’administration).

<?php function __construct( $id_base, $name, $widget_options = array(), $control_options = array() )

La seconde fonction à surcharger est la méthode widget(), définie ainsi :

<?php function widget($args, $instance)

Le premier argument est un tableau contenant des paramètres d’affichage que nous détaillerons lors de l’implémentation de la méthode. Ils permettent notamment d’obtenir un rendu du widget qui correspond au thème graphique utilisé. Le second argument contient les paramètres du widget sauvegardés dans la base de données, c’est-à-dire les paramètres que l’administrateur a définis lors de l’ajout du widget à la zone dédiée. Créez donc un fichier newsletterwidget.php contenant la classe Zero_Newsletter_Widget suivante :

<?php
class Zero_Newsletter_Widget extends WP_Widget
{
    public function __construct()
    {
        parent::__construct('zero_newsletter', 'Newsletter', array('description' => 'Un formulaire d\'inscription à la newsletter.'));
    }
    
    public function widget($args, $instance)
    {
        echo 'widget newsletter';
    }
}

La classe de notre widget est maintenant créée, il faut donc dire à WordPress que nous voulons l’utiliser, c’est-à-dire la déclarer en tant que widget.

Pour cela, on utilise la fonction register_widget(), qui prend en paramètre le nom de la classe du widget. Dans notre cas, l’appel sera le suivant :

<?php
register_widget('Zero_Newsletter_Widget');

Cependant, nous ne pouvons pas l’appeler à n’importe quel moment, il faut attendre que WordPress soit prêt à enregistrer l’existence des widgets. Ceci se fait grâce à une action widgets_init ; nous devons donc faire un appel à add_action() pour la déclaration du widget.

Ainsi, en utilisant les fonctions anonymes de PHP, l’enregistrement du widget devient :

<?php
add_action('widgets_init', function(){register_widget('Zero_Newsletter_Widget');});

Cette instruction est à placer dans le fichier newsletter.php, que nous avons créé à la fin du chapitre précédent.

<?php
include_once plugin_dir_path( __FILE__ ).'/newsletterwidget.php';

class Zero_Newsletter
{
    public function __construct()
    {
        add_action('widgets_init', function(){register_widget('Zero_Newsletter_Widget');});
    }
}

Le widget est dorénavant déclaré et se retrouve visible dans la liste proposée par WordPress lorsque l’on se rend dans le menu « Apparence > Widgets » (voir la figure suivante).

Le widget Newsletter
Le widget Newsletter

Les paramètres

Vous avez probablement remarqué que le widget n’a aucun paramètre disponible dans l’interface d’administration. Pourtant, il faudrait au minimum pouvoir définir un titre à afficher en haut du widget pour qu’il soit identifiable parmi les autres.

L’affichage du paramétrage du widget est complètement délégué à notre classe en surchargeant la méthode form(), qui prend en paramètre un tableau contenant les valeurs précédemment enregistrées.

Dans le formulaire que nous allons créer, il est important d’utiliser, pour la génération des attributs id et name de vos champs, deux méthodes définies par WP_Widget qui sont respectivement get_field_id() et get_field_name(). Ces deux méthodes vont générer un identifiant et un nom unique pour chaque champ qui utilisés par WordPress lors de la sauvegarde des valeurs, il est donc très important de les utiliser, sans quoi l’enregistrement des paramètres ne pourra pas fonctionner.

Voici donc comment nous allons redéfinir la méthode form() dans le fichier newsletterwidget.php.

<?php
public function form($instance)
{
    $title = isset($instance['title']) ? $instance['title'] : '';
    ?>
    <p>
        <label for="<?php echo $this->get_field_name( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
        <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; ?>" />
    </p>
    <?php
}

Vous pouvez maintenant définir une valeur pour le titre, et vérifier que celle-ci est bien sauvegardée (voir la figure suivante).

L'ajout du widget dans une zone dédiée
L'ajout du widget dans une zone dédiée

Le rendu final

Pour terminer notre widget, il faut maintenant modifier la méthode widget() afin d’afficher le paramètre titre et le champ d’enregistrement des emails.

La récupération d’un paramètre se fait au travers de la variable $instance contenant les paramètres du widget. Le titre est donc récupéré par l’instruction $instance['title']. Cela n’est cependant pas tout : il existe un filtre intitulé widget_title auquel peuvent se brancher des fonctions appliquant un traitement particulier pour les titres des widgets.

Il n’est bien sûr pas obligatoire de l’utiliser pour obtenir l’affichage du paramètre, mais gardez à l’esprit qu’un utilisateur de votre plugin pourrait vouloir utiliser ce filtre pour modifier l’affichage des widgets sur son thème. Il faut donc l’utiliser !

<?php
echo apply_filters('widget_title', $instance['title']);

Le formulaire d’enregistrement d’adresse sera très simple, car nous n’avons besoin que d’un seul champ de type input.

<form action="" method="post">
    <p>
        <label for="zero_newsletter_email">Votre email :</label>
        <input id="zero_newsletter_email" name="zero_newsletter_email" type="email"/>
    </p>
    <input type="submit"/>
</form>

J’ai volontairement laissé le champ action du formulaire vide, afin que l’utilisateur reste sur la même page lors de son inscription. Nous verrons plus bas comment récupérer les informations postées. Vous devriez donc avoir la méthode complète widget() suivante dans la classe Zero_Newsletter_Widget :

<?php
public function widget($args, $instance)
{
    echo $args['before_widget'];
    echo $args['before_title'];
    echo apply_filters('widget_title', $instance['title']);
    echo $args['after_title'];
    ?>
    <form action="" method="post">
        <p>
            <label for="zero_newsletter_email">Votre email :</label>
            <input id="zero_newsletter_email" name="zero_newsletter_email" type="email"/>
        </p>
        <input type="submit"/>
    </form>
    <?php
    echo $args['after_widget'];
}

Le widget est maintenant prêt et doit s'afficher correctement avec un champ d'enregistrement d'emails (voir la figure suivante).

Le widget est installé
Le widget est installé
  • Chaque nouveau widget doit être enregistré lors de l'événement widgets_init.

  • Les widgets doivent hériter de la classe WP_Widget et surcharger la méthode widget().

  • Le rendu du widget doit utiliser les paramètres fournis par le thème pour générer un code HTML cohérent avec celui-ci.

Example of certificate of achievement
Example of certificate of achievement