Tutoriel WordPress: Créer un widget

WordPress utilise nativement un système de « widgets » dans la barre latérale (la « sidebar »). Les widgets sont intiment liés au thème utilisé. Il est possible directement depuis un thème de créer son propre widget.

Nous allons donc voir ici, comment créer simplement un widget, qui affichera les photos d’un compte Flickr donné.

1. Préambule

Pour notre widget, nous allons avoir besoin de quatre paramètres :

• title: le titre du widget
• identifiant: l’identifiant du compte Flickr
• pseudo: le pseudonyme du compte Flickr
• nb_display: le nombre de photos à afficher

Nous verrons comment utiliser ces 4 paramètres dans les fonctions qui suivent.

A présent, rendez-vous dans votre le répertoire où est installé votre thème généralement situé ici:

/wp-content/themes/votre-theme/

Ouvrez ensuite le fichier functions.php et ajouter le code suivant :

<?php
class FlickrGallery extends WP_Widget {

	function FlickrGallery()
	{
		// Constructeur
	}

	function widget($args, $instance)
	{
		// Contenu du widget à afficher
	}

	function update($new_instance, $old_instance)
	{
		// Modification des paramètres du widget
	}

	function form($instance)
	{
		// Affichage des paramètres du widget dans l'admin
	}

}
?>

Pour créer un widget, nous devons donc créer une classe portant le nom de notre widget, en l’occurence « FlickrGallery« . Dans cette classe, nous disposons de quatre méthodes :

• FlickrGallery() : Il s’agit du constructeur, c’est ici que l’on va instancier le widget.
• widget() : Dans cette fonction, nous allons pouvoir définir le code html qui sera affiché dans notre widget.
• update() : Cette méthode s’occupe de mettre à jour les paramètres que l’on aura définis pour notre widget.
• form() : Cette fonction permet de définir le code html qui sera affiché dans l’administration pour saisir les paramètres.

Développement des fonctions

Méthode FlickrGallery()

function FlickrGallery()
{
	parent::WP_Widget(false, $name = 'FlickrGallery', array("description" => 'Affichage de votre galerie Flickr'));
}

Tout ce que l’on fait dans cette méthode, c’est appeler le constructeur de la classe parente « WP_Widget« , en lui passant trois paramètres :

1. Le premier est l’ID du widget, si false il sera défini automatiquement
2. Le deuxième est le nom du widget
3. Le troisième est un tableau de paramètres pour par exemple ajouter une description

Méthode widget()

C’est dans cette méthode que nous allons définir le code HTML qui sera affiché dans notre widget, dans la barre latérale.

Il y a un peu plus de code, c’est le gros morceau du widget :

<?php
function widget($args, $instance)
{
	// Extraction des paramètres du widget
	extract( $args );

	// Récupération de chaque paramètre
	$title = apply_filters('widget_title', $instance['title']);
	$identifiant = $instance['identifiant'];
	$pseudo = $instance['pseudo'];
	$nb_display = $instance['nb_display'];

	// Voir le détail sur ces variables plus bas
	echo $before_widget;

	// On affiche un titre si le paramètre est rempli
	if($title)
		echo $before_title . $title . $after_title;

	/* Début de notre script
	/* Nous allons ici récupérer un webservice de Flickr, un fichier XML
	/* Puis le parcourir
	/* Et afficher un nombre défini de photos */
	?>
	<ul>
	<?php
		$url = "http://api.flickr.com/services/feeds/photos_public.gne?id=".$identifiant."&lang=en-us&format=rss_200";
		$flickr = simplexml_load_file($url);

		if($flickr != false)
		{
			$nb = $nb_display;

			for($i = 0; $i<$nb; $i++)
			{
				$photo = $flickr->channel->item[$i];
				$picture = $photo->xpath("media:thumbnail");
				$pic = $picture[0]['url'];
				$w = $picture[0]['width'];
				$h = $picture[0]['height'];

				$title = $photo->title;

				echo "<li><a href='$photo->link' rel='external' title=\"$title\"><img src='$pic' alt=\"$title\" width='$w' height='$h' /></a></li>";
			}
		}
		else
			echo "<li>Erreur lors du chargement des photos Flickr.</li>";
	?>
	</ul>
	<div class="clear"></div>
	<p class="right"><a href="http://www.flickr.com/photos/<?php echo $pseudo; ?>/">Plus de photos</a></p>

	<?php echo $after_widget;
}

Voici le widget que nous aurons dans notre sidebar (après avoir rajouté un peu de CSS):

Méthode update()

<?php
function update($new_instance, $old_instance)
{
	$instance = $old_instance;

	/* Récupération des paramètres envoyés */
	$instance['title'] = strip_tags($new_instance['title']);
	$instance['identifiant'] = $new_instance['identifiant'];
	$instance['pseudo'] = $new_instance['pseudo'];
	$instance['nb_display'] = $new_instance['nb_display'];

	return $instance;
}
?>

Pas grand chose à expliquer ici, la fonction récupère les paramètres du widget, et WordPress s’occupe du reste, de la modification en base de données. Toute cette partie base de données est transparente pour nous !

Méthode form()

<?php
function form($instance)
{
	$title = esc_attr($instance['title']);
	$identifiant = esc_attr($instance['identifiant']);
	$pseudo = esc_attr($instance['pseudo']);
	$nb_display = esc_attr($instance['nb_display']);
	?>
		<p>
			<label for="<?php echo $this->get_field_id('title'); ?>">
				<?php _e('Title:'); ?>
				<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>

		<p>
			<label for="<?php echo $this->get_field_id('identifiant'); ?>">
				<?php _e('Identifiant:'); ?>
				<input class="widefat" id="<?php echo $this->get_field_id('identifiant'); ?>" name="<?php echo $this->get_field_name('identifiant'); ?>" type="text" value="<?php echo $identifiant; ?>" />
			</label>
		</p>

		<p>
			<label for="<?php echo $this->get_field_id('pseudo'); ?>">
				<?php _e('Pseudo:'); ?>
				<input class="widefat" id="<?php echo $this->get_field_id('pseudo'); ?>" name="<?php echo $this->get_field_name('pseudo'); ?>" type="text" value="<?php echo $pseudo; ?>" />
			</label>
		</p>

		<p>
			<label for="<?php echo $this->get_field_id('nb_display'); ?>">
				<?php _e('Nombre de photos:'); ?>
				<input class="widefat" id="<?php echo $this->get_field_id('nb_display'); ?>" name="<?php echo $this->get_field_name('nb_display'); ?>" type="text" value="<?php echo $nb_display; ?>" />
			</label>
		</p>
	<?php
}
?>

Ici, nous allons simplement récupérer les informations enregistrées en base de données et afficher des champs de formulaire pour les modifier. Nous utilisons pour cela deux méthodes :

• $this->get_field_id(‘identifiant’) : permet de récupérer l’ID du paramètre
• $this->get_field_name(‘identifiant’): permet de récupérer le nom du paramètre

Voilà ! Nos quatre fonctions sont terminées ! Il nous reste encore une chose à faire :

• Dire à WordPress d’inclure ce widget

Dernière étape

Rajoutez juste après la classe FlickGallery la ligne de code suivante :

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

Nous indiquons à WordPress d’ajouter notre widget FlickGallery à la liste des widgets à initialiser.

Et voici le widget que nous avons dans l’administration :

Pour peaufiner

Vous avez sans doute vu que nous avons utilisé quatre variables qui sortent de nulle part tout à l’heure :

1. $before_widget
2. $after_widget
3. $before_title
4. $after_title

Ces variables correspondent au code HTML qu’il est possible d’adapter à notre thème.

Ainsi, vous trouverez dans le fichier functions.php un bout de code comme celui-là :

<?php
if(function_exists('register_sidebar'))
    register_sidebar(array(
		'before_widget' => '<li id="%1$s" class="widget %2$s">',
		'after_widget' => "</li>n",
		'before_title' => '<h2 class="widgettitle">',
		'after_title' => "</h2>n"
	));
?>

Vous pouvez donc ici modifier le code HTML qui entoure le titre du widget ainsi que l’élément de liste lui même.

A vous de jouer !

Voilà ! Vous avez maintenant toutes les clés en main pour construire vos propres widgets de thème ! Bon développement !