Les widgets WordPress sont des blocs de contenu HTML statique ou dynamique qui peuvent être ajoutés à des zones spécifiques des pages de l’interface publique (zones de widgets ou barres latérales). WordPress fournit un bon nombre de widgets intégrés, tels que Archives, Catégories, Nuage d’étiquettes, Recherche, Articles récents, Calendrier, et plus encore. De plus, comme je vais l’expliquer dans cet article, les développeurs d’extensions peuvent facilement créer un widget WordPress à partir de zéro, ajouter des fonctionnalités personnalisées et du contenu spécifique à tout thème supportant cette caractéristique étonnante.

Widgets Écran

Écran Widget dans Twenty Seventeen

Vous pouvez trouver des tonnes de widgets WordPress dans la section du dépot d’extension (actuellement plus de 50 000), sur les marchés WordPress et les sites des vendeurs, et vous trouverez probablement tous les widgets dont vous pourriez avoir besoin. Quoi qu’il en soit, de temps en temps vous ne trouverez pas le widget que vous cherchez, et vous aurez besoin de construire votre propre widget.

Widgets WordPress dans le dépôt des extensions

Widgets WordPress dans le dépôt des extensions

La structure de base des widgets WordPress

Du point de vue du développeur, un widget est une instance de la classe WP_Widget. Ainsi, afin de construire un widget personnalisé, nous devons étendre cette classe à partir d’une extension. Notre première tâche est de créer un nouveau fichier.php dans le dossier /wp-content/plugins/my-widget/ ayant l’en-tête suivant :

<?php
/*
Plugin Name: My Widget
Plugin URI: http://wordpress.org/extend/plugins/#
Description: This is an example plugin 
Author: Your Name
Version: 1.0
Author URI: http://example.com/
*/

Ce n’est qu’un simple en-tête d’extension, mais c’est suffisant pour nos besoins (vous trouverez de plus amples informations dans le Codex). Enregistrez le script sous my-widget.php, allez dans l’écran des Extensions, et activez l’extension. Maintenant, nous devons étendre la classe WP_Widget et certaines de ses fonctions à un moment précis de l’exécution de WordPress. Ajoutons le code suivant à notre extension :

// register My_Widget
add_action( 'widgets_init', function(){
	register_widget( 'My_Widget' );
});

La fonction add_action permet d’accrocher un rappel (callback) personnalisé à la fonction widgets_init, qui se déclenche après que tous les widgets par défaut ont été enregistrés.

Note : un hook d’action permet d’exécuter une fonction à un point spécifique de l’exécution de WordPress et de ses extensions (voir le Codex WordPress pour plus d’informations)

La fonction register_widget enregistre le widget spécifié, qui est une extension de la classe WP_Widget :

class My_Widget extends WP_Widget {
	// class constructor
	public function __construct() {}
	
	// output the widget content on the front-end
	public function widget( $args, $instance ) {}

	// output the option form field in admin Widgets screen
	public function form( $instance ) {}

	// save options
	public function update( $new_instance, $old_instance ) {}
}

Pour construire notre widget simple, il nous suffit d’utiliser quatre méthodes de classe :

  • __construct est le constructeur de classe et permet de définir des paramètres de widget personnalisés.
  • widget() fait écho au contenu du widget sur l’interface publique.
  • form() affiche les éléments de formulaire d’administration du widget.
  • update() met à jour l’objet widget actuel.

Vous pouvez obtenir ce code à partir de Gist. Une fois que nous avons mis en place un modèle d’extension de base, nous pouvons faire un pas en avant, et définir chaque méthode de sous-classe.

Configurer le widget : le constructeur de classe

Le constructeur de classe enregistre l’ID du widget, le titre et les options supplémentaires, comme le nom de classe, la description, base_id, largeur et hauteur. Dans notre exemple de widget, nous attribuons l’ID, le nom et deux options de widget :

public function __construct() {
	$widget_ops = array( 
		'classname' => 'my_widget',
		'description' => 'A plugin for Kinsta blog readers',
	);
	parent::__construct( 'my_widget', 'My Widget', $widget_ops );
}
  • mon_widget est l’ID de base du widget
  • ‘Mon Widget’ est le titre du widget
  • $widget_ops est un tableau d’options

Voir le Code référence pour la liste complète des options disponibles.

Construction du formulaire d’administration

Ensuite, nous devons construire un formulaire d’administration permettant aux utilisateurs de définir des options personnalisées pour le widget. Pour accomplir cette tâche, nous définissons la méthode form() comme ci-dessous :

public function form( $instance ) {
	$title = ! empty( $instance['title'] ) ? $instance['title'] : esc_html__( 'Title', 'text_domain' );
	?>
	<p>
	<label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>">
	<?php esc_attr_e( 'Title:', 'text_domain' ); ?>
	</label> 
	
	<input 
		class="widefat" 
		id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" 
		name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" 
		type="text" 
		value="<?php echo esc_attr( $title ); ?>">
	</p>
	<?php
}

La fonction form() conserve en argument un tableau des options du widget actuel. L’élément ‘title’ de $instance fournit l’option de titre, tandis que get_field_id et get_field_name définissent l’ID et le nom du champ texte.

Basic widget form

Une forme de widget très basique avec un seul champ de saisie

Cet exemple simple montre comment obtenir les valeurs des options de la base de données, et les utiliser pour construire un formulaire d’administration pour configurer le comportement du widget. Évidemment, nous ne sommes pas limités aux champs de texte. Le code suivant fournit une liste de contrôle des articles les plus récents :

public function form( $instance ) {

	$posts = get_posts( array( 
			'posts_per_page' => 20,
			'offset' => 0
		) );
	$selected_posts = ! empty( $instance['selected_posts'] ) ? $instance['selected_posts'] : array();
	?>
	<div style="max-height: 120px; overflow: auto;">
	<ul>
	<?php foreach ( $posts as $post ) { ?>

		<li><input 
			type="checkbox" 
			name="<?php echo esc_attr( $this->get_field_name( 'selected_posts' ) ); ?>[]" 
			value="<?php echo $post->ID; ?>" 
			<?php checked( ( in_array( $post->ID, $selected_posts ) ) ? $post->ID : '', $post->ID ); ?> />
			<?php echo get_the_title( $post->ID ); ?></li>

	<?php } ?>
	</ul>
	</div>
	<?php
}

La fonction get_posts() fournit un tableau d’articles basé sur les paramètres spécifiés. Dans notre exemple, nous n’obtenons que les vingt derniers articles par ordre chronologique, mais nous pouvons construire des requêtes plus avancées en définissant n’importe quelle combinaison des variables de requête disponibles (voir le Codex pour une liste complète des variables de requête).

Ensuite, un opérateur ternaire vérifie si une valeur valide de $instance[‘selected_posts’] existe. Sinon, la valeur de $selected_posts est définie sur un tableau vide. Le cycle foreach itère sur les éléments de $posts, et affiche une case à cocher pour chacun d’eux. La fonction checked compare deux arguments et imprime l’attribut coché s’ils sont identiques.

L’image ci-dessous montre le formulaire d’administration du widget en cours.

Form

Mise à jour des options du widget

La méthode update() met à jour une instance d’un widget. Nous définissons la fonction comme ceci :

public function update( $new_instance, $old_instance ) {
	$instance = array();
	$instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : '';
		
	$selected_posts = ( ! empty ( $new_instance['selected_posts'] ) ) ? (array) $new_instance['selected_posts'] : array();
	$instance['selected_posts'] = array_map( 'sanitize_text_field', $selected_posts );

	return $instance;
}

La fonction conserve deux arguments :

  • $new_instance est un tableau de réglages tel que soumis par l’utilisateur
  • $old_instance est un tableau de réglages tels que stockés dans la base de données

Voici ce qui se passe :

  • $instance[‘title’] stocke la nouvelle valeur du titre du widget ou une chaîne vide si elle n’est pas disponible.
  • $selected_posts stocke les ID des articles sélectionnés par l’utilisateur ou un tableau vide.
  • $instance[‘selected_posts’] stocke une version sanitisée de $selected_posts
  • la fonction retourne $instance

Le formulaire du widget est maintenant en action et les options de l’utilisateur peuvent être enregistrées dans la base de données WordPress. Notre dernière tâche est d’afficher les résultats sur l’interface publique du site.

L’affichage du widget

La méthode widget() affiche le contenu du widget sur l’interface publique du site. La fonction récupère les articles sélectionnés et exécute un cycle foreach qui produit un élément de liste pour chaque article. La fonction widget est définie comme ceci :

public function widget( $args, $instance ) {
	echo $args['before_widget'];
	if ( ! empty( $instance['title'] ) ) {
		echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ) . $args['after_title'];
	}

	if( ! empty( $instance['selected_posts'] ) && is_array( $instance['selected_posts'] ) ){ 

		$selected_posts = get_posts( array( 'post__in' => $instance['selected_posts'] ) );
		?>
		<ul>
		<?php foreach ( $selected_posts as $post ) { ?>
			<li><a href="<?php echo get_permalink( $post->ID ); ?>">
			<?php echo $post->post_title; ?>
			</a></li>		
		<?php } ?>
		</ul>
		<?php 
		
	}else{
		echo esc_html__( 'No posts selected!', 'text_domain' );	
	}

	echo $args['after_widget'];
}

La fonction widget() conserve deux arguments :

  • $args est un tableau d’arguments incluant ‘before_title’, ‘after_title’, ‘before_widget’ et ‘after_widget’.
  • $instance est un tableau de réglages du widget

Si un titre valide est trouvé, il est sanitisé à l’aide du filtre widget_title. Ensuite, si au moins un article a été sélectionné, get_posts retourne un tableau d’objets d’article. Enfin, le cycle foreach établit une liste pour chaque article sélectionné. Le code complet de cette extension est disponible sur Gist.

Widget

Un widget simple affichant la liste des articles sélectionnés par l’administrateur du site

Récapitulatif

Toute personne ayant une connaissance de base de PHP et du développement WordPress peut rapidement apprendre à construire ses propres widgets WordPress. Même si vous n’êtes pas encore développeur WordPress, la création d’un widget pourrait vous donner l’occasion d’une première approche du développement d’extension. Prêt à créer votre propre widget WordPress ?

21
Partages