Ecriture d’un plugin Wordpress, 2e partie : la structure d’un plugin Twitter

Nous avons vu dans un article précédent les bases de l’écriture d’un plugin. Cet article nous donnera l’occasion de voir une application plus concrète, avec l’écriture d’un plugin qui récupère les tweets d’un utilisateur pour les afficher sur un site WordPress. Il va sans dire qu’un plugin Twitter est quelque chose de très original, étant donné qu’il y a déjà 465 plugins sur Twitter à l’heure qu’il est sur le répertoire officiel .

1 - Récupérer le code du widget Twitter

Nous n’allons pas plonger dans les arcanes de l’API de Twitter pour l’écriture de ce plugin. Nous nous contenterons de nous servir du widget que Twitter met à disposition ici (http://twitter.com/goodies/widget_profile). Ce code récupère les récents tweets d’un utilisateur et les affiches sur n’importe quelle page Web où le widget est inséré. Pour notre test, nous allons récupérer les tweets de Damon Lindelof, co-créateur et maître à penser de la série Lost. Twitter donne le code suivant :

<script src="http://widgets.twimg.com/j/2/widget.js"></script>
<script>
new TWTR.Widget({
  version: 2,
  type: 'profile',
  rpp: 4,
  interval: 6000,
  width: 250,
  height: 300,
  theme: {
    shell: {
      background: '#333333',
      color: '#ffffff'
    },
    tweets: {
      background: '#000000',
      color: '#ffffff',
      links: '#4aed05'
    }
  },
  features: {
    scrollbar: false,
    loop: false,
    live: false,
    hashtags: true,
    timestamp: true,
    avatars: false,
    behavior: 'all'
  }
}).render().setUser('DamonLindelof').start();
</script>

2- Préparation

Avant de plonger directement dans l’écriture du plugin, voyons d’abord ce qu’on va pouvoir faire avec ce widget. A l’évidence, on va l’afficher sur un sidebar. Mais le plugin n’a aucun intérêt si l’utilisateur est coincé avec le compte twitter de Damon Lindelof, surtout s’il n’aime pas Lost ! On va donc lui donner la possibilité de choisir le compte de son choix. De plus, les couleurs choisies ici sont purement aléatoires. L’utilisateur voudra sans doute les modifier pour les adapter à la charte graphique de son site. Nous lui donnerons aussi la possibilité de modifier d’autres comportements du widget (en gras dans le code précédent, les éléments que l’utilisateur pourra modifier). En un mot, nous allons prendre du code statique, et nous allons le pluginiser !

3- Etape 1 : afficher le widget

Nous avons déjà vu les bases de l’écriture de plugin. Ici, on nommera le plugin TwitterInTheSidebar (pour faire simple !), et on le mettra dans le dossier du même nom. N’oubliez pas de toujours vérifier les permissions du dossier. Si vous avez tout fait parfaitement et que Wordpress n’arrive pas à trouver le plugin, il y a fort à parier que vous n’avez pas mis les bonnes permissions au dossier (et au fichier PHP).

Nous avons vu précédemment qu’il faut accorder une attention spéciale aux noms afin d’éviter tous conflits. Une solution est l’utilisation de noms très longs. Il y a une autre solution plus élégante : mettre le plugin dans sa propre classe. Elle fera sans doute l’objet d’un futur article.

On commence par écrire une fonction afficheTweet(), qui se contente d’afficher le widget récupéré sur Twitter. Notez qu’en raison de l’utilisation de la syntaxe HEREDOC, la balise fermante du texte, TWEET, ne doit pas être indenté, il ne doit y avoir ni texte, ni espace, ni tabs avant. La fonction tweetDansSidebar() « widgetise » le plugin, selon la terminologie WordPressienne. Cela permet de disposer d’un Widget dans la page Widgets de WordPress, et facilite ainsi l’insertion du plugin dans une sidebar sans devoir coder en dur un code PHP dans le thème.

Le code complet :

<?php
/*
Plugin Name: TwitterInTheSidebar
Description: Récupère les tweets d'un compte twitter et les affiche dans une sidebar
Version: 1.0
*/

// Affiche les tweets de DamonLindelof
function afficheTweet() {
	echo <<<TWEET
	<script src="http://widgets.twimg.com/j/2/widget.js"></script>
	<script>
	new TWTR.Widget({
	  version: 2,
	  type: 'profile',
	  rpp: 4,
	  interval: 6000,
	  width: 250,
	  height: 300,
	  theme: {
		shell: {
		  background: '#333333',
		  color: '#ffffff'
		},
		tweets: {
		  background: '#000000',
		  color: '#ffffff',
		  links: '#4aed05'
		}
	  },
	  features: {
		scrollbar: false,
		loop: false,
		live: false,
		hashtags: true,
		timestamp: true,
		avatars: false,
		behavior: 'all'
	  }
	}).render().setUser('DamonLindelof').start();
	</script>
TWEET;
	}

//widgétise le plugin: les tweets peuvent maintenant être insérés dans une sidebar.
function tweetDansSidebar() {
	if (!function_exists('register_sidebar_widget')) {
		return;
		}
	register_sidebar_widget('Afficher Twitter', 'afficheTweet');
	}

 add_action('init','tweetDansSidebar');

Activez le plugin et vous verrez le nom du widget (Afficher Twitter) dans la page Widgets de Wordpress :

Petite astuce : les widgets sont classés par défaut par ordre alphabétique. Profitez-en pour afficher le vôtre parmi les premiers en lui donnant un nom commençant par « A » par exemple, afin qu’on puisse facilement le repérer !
Glissez le widget Affiche Twitter dans une sidebar, et voyez le résultat :

Le plugin s’affiche sur le blog, mais il est beaucoup trop large par rapport au thème par défaut, sans compter que la couleur ne concorde pas ! Pour pouvoir ajouter des options permettant à l’utilisateur d’adapter le widget, nous allons donc devoir écrire une interface d’administration, qui recueillera les choix de l’utilisateur, et ensuite stocker ces choix dans la base de données et les récupérer afin de pouvoir les utiliser.

4- Etape 2 : écrire l’interface d’administration

Une page d’administration n’est autre qu’un formulaire web chargé de récupérer les choix de l’utilisateur. Pour plus de simplicité, nous mettrons l’interface dans sa propre page :
TwitterInTheSidebarAdmin.php

<div class="wrap twitter-in-the-sidebar">
<h2>Options de personnalisation de Twitter In The Sidebar</h2>
<form method="post" action="options.php">
  <ul>
    <li><label for="account">Nom du compte Twitter:<input type="text" width="150" id="account" /></label></li>
  	<li><label for="width">Largeur du widget:<input type="text" width="50" id="width" /></label></li>
    <li><label for="height">Hauteur du widget: <input type="text" width="50" id="height" /></label></li>
    <li><label for="shell-background-color">Couleur de fond du cadre: #<input type="text" width="100" id="shell-background-color" /></label></li>
    <li><label for="shell-color">Couleur du texte du cadre: #<input type="text" width="100" id="shell-color" /></label></li>
    <li><label for="tweets-background-color">Hauteur du widget: #<input type="text" width="100" id="tweets-background-color" /></label></li>
    <li><label for="tweets-color">Hauteur du widget: #<input type="text" width="100" id="tweets-color" /></label></li>
    <li>&nbsp;</li>
    <li><input  class="button-primary" type="submit" name="Save" value="<?php _e("Save Options"); ?>" id="submitbutton" /></li>
  </ul>
</form>
</div>

Comme vous le voyez, il s’agit d’un formulaire très simple, et la page se mettra automatiquement aux couleurs de Wordpress. On va juste lui adjoindre une feuille de style CSS afin de bien aligner les champs input :
TwitterInTheSidebar.css

/* Styles css pour le plugin TwitterInTheSidebar*/

.twitter-in-the-sidebar {
	width:450px;
	}

.twitter-in-the-sidebar textarea,
.twitter-in-the-sidebar input[type="text"],
.twitter-in-the-sidebar input[type="password"],
.twitter-in-the-sidebar input[type="file"],
.twitter-in-the-sidebar input[type="button"],
.twitter-in-the-sidebar input[type="submit"],
.twitter-in-the-sidebar input[type="reset"],
.twitter-in-the-sidebar select {
	float:right;
	}

Nous avons donc les éléments en main (Formulaire et feuille de style). Nous allons maintenant voir comment les intégrer dans notre plugin. Dans le code ci-dessous, la fonction adminPanel() va inclure le formulaire dans le plugin à travers un simple include, et la fonction twitterCSS () affiche le lien vers la feuille de style TwitterInTheSidebar.css située dans le même répertoire que notre fichier principal. La suite nécessite un peu plus d’explications.

La fonction addTwitterAdmin() comporte deux éléments essentiels :
add_options_page() est une fonction Wordpress qui permet d’ajouter la page dans le menu Réglages de Wordpress, de définir l’URL de la page, de donner le titre de la page et de définir quel type d’utilisateur peut y accéder. Sa signature est comme suit :
add_options_page(Titre de la page, Titre du sous-menu de la page, Rôle /Capacité de l’utilisateur, url de la page, fonction affichant l’interface du plugin );
Vous remarquerez dans le code suivant la variable $hook qui récupère la valeur retournée par add_options_page. Cette variable récupère le hook du plugin, c'est-à-dire l’action unique qui se déclenche lorsque le plugin est utilisé. Nous avons déjà vu les hooks de WordPress précédemment avec les actions et les filters. Notre plugin dispose automatiquement de son propre hook (ce qui permettra par exemple à un autre plugin de s’y greffer). Ce hook sert ensuite dans la ligne suivante :

add_action("admin_head-{$hook}", 'twitterCSS' );

Je ne sais pas pour vous, mais une des choses qui m’irrite le plus est la présence permanente de CSS ou Javascripts utilisés par un plugin dans toutes les pages admin de Wordpress. Au-delà de la surcharge que représente ces fichiers, leur présence amplifie les risques de conflits entre vos variables et fonctions Javascripts et ceux des autres plugins, et de même pour les styles CSS.
La ligne précédente règle ce problème. Avec cette ligne, nous demandons à Wordpress d’exécuter la fonction twitterCSS (qui affiche le CSS) entre les balises de l’admin de Wordpress, mais uniquement lorsque la page affichée est l’interface d’administration de notre plugin ! Utilisez cette fonction dans votre plugin, et vous éviterez des heures de débogage aux auteurs des autres plugins, alors que le « bug » est juste un conflit CSS ou JavaScript !
La ligne finale intègre le tout aux pages d’administration de WordPress. Voici donc l’intégralité (provisoire) du code ajouté à TwitterInTheSidebar.php (vous aurez le code complet et final dans le 2e article de ce plugin Twitter).

//récupère le formulaire d'administration du plugin
 function adminPanel() {
 	include("TwitterInTheSidebarAdmin.php");
 }

 function twitterCSS() {
 	$siteurl = get_option('siteurl');
    $url = $siteurl . '/wp-content/plugins/' . basename(dirname(__FILE__)) . '/TwitterInTheSidebar.css';
 	echo "<link href='$url' rel='stylesheet' type='text/css' />";
    }

 function addTwitterAdmin() {
    $hook = add_options_page("Options pour l'affichage de Twitter",
                     "Options Twitter",
                     "administrator",
                     "twitteroptions",
                     "adminPanel"
                     );
      //Garantit que le style s'ajoute seulement notre page d'admin et ne vienne pas empiéter sur les autres pages
     add_action("admin_head-{$hook}", 'twitterCSS' );
     }

 //intègre le tout aux pages Admin de Wordpress
 add_action("admin_menu", "addTwitterAdmin");

Résultat :

La page d’administration du plugin est disponible dans le menu Réglages.

Et voilà la page d’administration du plugin. Pas mal, non ?

Et voilà, nous avons le squelette de notre plugin. Il nous reste maintenant à faire l’essentiel : écrire le code qui permette de transformer ce squelette en plugin complet. Ce sera l’objet de l’article suivant : finaliser le plugin Twitter.