Création de widgets

Les widgets Dotclear sont des petits bouts de code très simples permettant d'afficher diverses informations dans les bandeaux latéraux d'un blog.

Nous allons voir ici comment réaliser un widget très simple.

Comme toujours, on commence par créer un répertoire dans le répertoire des plugins et on crée un fichier _define.php :

<?php
if (!defined('DC_RC_PATH')) { return; }
 
$this->registerModule(
	/* Name */			"My first widget",
	/* Description*/		"This is my first widget",
	/* Author */			"Peter McAlloway",
	/* Version */			'1.0',
	/* Permissions */		'admin'
);
?>

Ceci fait, nous allons faire un fichier particulier appelé _widgets.php dans lequel nous allons écrire le code suivant :

<?php
if (!defined('DC_RC_PATH')) { return; }
 
global $core;
 
$core->addBehavior('initWidgets',
	array('myWidgetBehaviors','initWidgets'));
 
class myWidgetBehaviors
{
	public static function initWidgets($w)
	{
		$w->create('MyWidget',__('My first widget'),
			array('publicMyWidget','myWidget'));
	}
}
?>

Ce premier code est très simple. La première ligne appelle le comportement initWidgets et indique d'appeler la méthode statique initWidgets de la classe myWidgetBehaviors. La classe est définie juste en dessous et la méthode en question se contente de créer le widget.

La fonction initWidgets reçoit l'objet contenant les widgets en argument. L'unique ligne de cette méthode lance la création du widget.

La méthode create de l'objet passé en argument prend les paramètres suivants :

• L'identifiant du widget
• Le nom du widget
• Un callback valide pour l'affichage du widget sur la partie publique du blog.

En clair nous disons ici : créer un widget identifié par MyWidget, nommé My first widget et appelant la méthode statique myWidget de la classe publicMyWidget.

Nous allons maintenant rendre ce widget disponible dans l'administration du blog. Pour ce faire, il suffit d'éditer le fichier _admin.php, en y ajoutant les lignes suivantes :

<?php
if (!defined('DC_CONTEXT_ADMIN')) { return; }
 
require dirname(__FILE__).'/_widgets.php';
?>

Vous pouvez dès lors voir votre widget dans la liste des widgets disponibles. Il nous manque encore cependant un élément essentiel : ce que fait le widget sur la partie publique du blog.

Nous créons un fichier _public.php dans lequel nous allons écrire le code suivant :

<?php
if (!defined('DC_RC_PATH')) { return; }
 
require dirname(__FILE__).'/_widgets.php';
 
class publicMyWidget
{
	public static function myWidget($w)
	{
		return '<p><strong>Hello World!</strong></p>';
	}
}
?>

Le widget que nous venons de créer ne sert pas à grand chose et il serait bon de lui ajouter quelques options ou paramètres.

Nous reprenons le code du fichier _widgets.php et le changeons par :

<?php
if (!defined('DC_RC_PATH')) { return; }
 
global $core;
 
$core->addBehavior('initWidgets',
	array('myWidgetBehaviors','initWidgets'));
 
class myWidgetBehaviors
{
	public static function initWidgets($w)
	{
		$w->create('MyWidget',__('My first widget'),
			array('publicMyWidget','myWidget'));
 
		$w->MyWidget->setting('title',__('Title:'),
			'default value','text');
 
		$w->MyWidget->setting('checked',__('checkbox'),
			true,'check');
 
		$w->MyWidget->setting('text',__('Text:'),
			'','textarea');
 
		$w->MyWidget->setting('option',__('Options:'),
			null,'combo',array('opt1' => 1, 'opt2' => 2));
	}
}
?>

Vous aurez remarqué la présence de 4 nouvelles lignes dans le code. Chacune ajoute une option différente au widget MyWidget. Pour ajouter une option à un widget on appelle la méthode $w→MyWidget→setting() ou MyWidget est l'identifiant du widget. Voici ce que font ces quatres lignes :

• On ajoute une option title nommée "Title:" ayant pour valeur par défaut "default value" et de type text (champ texte simple).
• On ajoute une option checked nommée "checkbox", cochée par défaut et de type check (case à cocher).
• On ajoute une option text nommée "Text:" avec aucune valeur par défaut et de type textarea (champs de texte long).
• On ajoute une option option nommée "Options:" n'ayant pas de valeur par défaut et de type combo (liste de choix).

Ce code donne tous les types d'options possibles pour un widget.

Maintenant que nous avons un widget paramétrable, nous allons pouvoir changer le fichier _public.php par ceci :

<?php
if (!defined('DC_RC_PATH')) { return; }
 
require dirname(__FILE__).'/_widgets.php';
 
class publicMyWidget
{
	public static function myWidget($w)
	{
		return '<p><strong>Title: '.$w->title.'</strong></p>';
	}
}
?>

Vous l'aurez compris, pour obtenir la valeur d'une option d'un widget, il suffit d'appeler $w→identifiant_option. Dans notre cas, nous pourrions appeler $w→checked, $w→text, $w→option.

Vous savez maintenant (presque) tout. Bons widgets !