====== Création de widgets ======

===== Introduction =====

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.

===== Conception du plugin =====

==== Définition ====

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

<code 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'
);
?>
</code>

==== Création du widget et administration ====

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

<code php>
<?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'));
	}
}
?>
</code>

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**.

<note important>
Attention à ne pas réutiliser l'identifiant d'un widget déjà existant. Vous pouvez cependant le faire si vous tenez explicitement à remplacer un widget déjà existant.
</note>

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 :
<code php>
<?php
if (!defined('DC_CONTEXT_ADMIN')) { return; }

require dirname(__FILE__).'/_widgets.php';
?>
</code>

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.

==== Affichage du widget ====

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

<code php>
<?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>';
	}
}
?>
</code>
<note>
L'inclusion du fichier **_widgets.php** dans le fichier **_public.php** permet d'inclure ce widget directement dans les fichiers template, via le marqueur <tpl:Widget>. Cette fonctionnalité est disponible depuis la version 2.1 de dotclear.
</note>

===== Paramètres avancés du Widget =====

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.

==== Ajout d'options ====

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

<code php>
<?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));
	}
}
?>
</code>

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.

<note>
La méthode setting() du widget prend un paramètre supplémentaire contenant les données quand elle est de type **combo**.
</note>

==== Utilisation des options côté admin ====

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

<code php>
<?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>';
	}
}
?>
</code>

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 !