====== Manuel de création de plugins pour Dotclear 2 ======

===== Introduction =====

Les plugins sont des fragments applicatifs permettant d'ajouter des fonctionnalités à Dotclear, comme par exemple une liste de liens, un outil pour importer un blog depuis un autre logiciel ou encore une nouvelle syntaxe de rédaction des billets.

La réalisation d'un plugin demande simplement des connaissances assez solides en PHP, notamment en programmation orientée objet. Dans la mesure du possible des liens vers des points précis de la documentation PHP seront fournis tout au long de ce manuel.

===== Premier plugin =====

Nous allons réaliser un premier plugin qui ne sert à rien d'autre qu'afficher un texte sur la partie publique du blog. Nous y ajouterons ensuite quelques agréments permettant de survoler une bonne partie de ce que peuvent faire des plugins Dotclear.

==== Définition d'un plugin ====

Un plugin est un répertoire se trouvant dans le répertoire des plugins (défini par DC_PLUGIN_ROOT). Nous allons donc créer un répertoire HelloWorld. Dans ce répertoire, pour que le plugin existe, nous devons ajouter un fichier **_define.php** contenant le code suivant :
<code php>
<?php
if (!defined('DC_RC_PATH')) { return; }

$this->registerModule(
        /* Name */                      "Hello World",
        /* Description*/                "Simple Hello World plugin",
        /* Author */                    "Olivier Meunier",
        /* Version */                   '1',
        array(
            'type'        =>            'plugin',
            'permissions' =>            'usage,contentadmin'
            /* et autres propriétés complémentaires */
        )
);
?>
</code>

<note>
Avant dotclear 2.4, la syntaxe suivante était utilisée. Elle est toujours possible, mais ne permet pas de profiter des propriétés complémentaires :
<code php>
<?php
if (!defined('DC_RC_PATH')) { return; }

$this->registerModule(
        /* Name */                      "Hello World",
        /* Description*/                "Simple Hello World plugin",
        /* Author */                    "Olivier Meunier",
        /* Version */                   '1',
        /* Permissions */               'usage,contentadmin'
);
?>
</code>
</note>

Les champs de la fonction **registerModule** sont accompagnés de commentaires afin de faciliter la lecture et l'édition du fichier **_define.php**. Tous ces champs sont simples à comprendre, nous nous arrêterons donc uniquement sur le champ **Permissions**. Ce champ prend une liste de permissions séparées par des virgules et ne sert que pour contrôler l'activation du plugin sur l'interface d'administration du blog. Si les permissions de l'utilisateur ne sont pas remplies, le plugin ne sera jamais chargé par l'interface d'administration.

Ici, nous décidons que le plugin sera chargé pour n'importe quel utilisateur pouvant se connecter sur l'interface d'administration, ce qui correspond aux droits //usage,contentadmin//. Si nous avions voulu restreindre ce plugin aux seuls administrateurs d'un blog donné, nous aurions assigné le droit //admin//.

<note>
Notez bien que les droits définis correspondent à ceux pour le blog en cours d'utilisation. Si le plugin avait la permission //admin// et qu'un utilisateur soit administrateur sur un blog A mais uniquement rédacteur sur un blog B, le plugin ne serait actif que sur le blog A.
</note>

Enfin, si vous souhaitez rendre un plugin uniquement utilisable par les super-administrateurs la permission doit être mise à //null// (sans guillemets).

Les propriétés complémentaires disponibles (via le tableau en fin d'appel) sont les suivantes :

^ Paramètre ^ Thème/Plugin ^ Description ^
| type         | T+P | à positionner à 'theme' ou 'plugin'|
| standalone_config | T | Définit si le thème définit ses propres modules de configuration, ou repose sur des mécanismes simplifiés de dotclear|
| parent | T | Nom du thème parent (héritage) |
| tplset | T | Nom du set de templates à utiliser |
| permissions    | P | Permissions du plugin|
| priority | P+T | priorité du module (1000 par défaut, les plus petites priorités sont chargés en premier) |
| widgettitleformat | T | Format des titres des widgets (ex : <h3 class="widget-title">%s</h3>) |
| widgetsubtitleformat | T | Format des sous-titres des widgets  (ex : <h4 class="widget-subtitle">%s</h4>) |


A noter qu'il est bon de traduire les champs //Name// et //Description// de ce fichier. Pour aider les logiciels de traduction, une bonne pratique consiste à ajouter en début de fichier //_admin.php// les chaines à traduire comme ceci:

<code php>
<?php
if (!defined('DC_ADMIN_CONTEXT')) { return; }

__('Hello wolrd'); /* Name */
__('Simple Hello World plugin'); /* Description */

?>
</code>

==== Structure d'un plugin ====

Notre plugin ne sert pour l'instant à rien du tout. Pour lui faire réaliser des actions, nous devons définir d'autres fichiers.

Un plugin possède trois autres fichiers (qui ne sont pas obligatoires selon les cas) :

  * **_admin.php** : définit le comportement du plugin sur l'interface d'administration.
  * **_public.php** : définit le comportement du plugin sur le blog. 
  * **_prepend.php** : définit les fichiers nécessaires à charger.

Nous verrons le fichier **_admin.php** plus tard et allons nous concentrer sur **_public.php** et **_prepend.php**.

C'est grâce à **_prepend.php** que vous allez pouvoir charger les fichiers nécessaires au bon fonctionnement du plugin.

<code php>
<?php

global $__autoload;
$__autoload['nomDeLaClassePhp'] = dirname(__FILE__).'/inc/class.nom.de.la.classe.php';

?>
</code>

C'est aussi dans ce fichier que les appels aux behaviors doivent être fait.

<note>
Un fichier peut contenir plusieurs classes. Dans ce cas là, il vous suffit d'inclure **qu'une seule fois** le fichier avec pour clé du tableau $__autoload la première classe présente dans le fichier en question. Les autres classes seront alors automatiquement chargées
</note>

<note>
Pour plus de précisions sur la nomenclature et la structure d'un plugin, référez vous à [[http://fr.dotclear.org/documentation/2.0/resources/plugins/files|cette page]]
</note>

C'est grâce à **_public.php** que nous allons afficher un texte sur la partie publique du blog. Nous créons donc un **_public.php** avec le code suivant :

<code php>
<?php
if (!defined('DC_RC_PATH')) { return; }

global $core;

$core->url->register('helloworld','helloworld','^helloworld$',array('HelloURL','HelloWorld'));

class HelloURL extends dcUrlHandlers
{
        public static function HelloWorld($args)
        {
                header('Content-Type: text/plain');
                echo 'Hello World!';
                exit;
        }
}
?>
</code>

Ce code est court mais nous allons y préter toute notre attention. Nous venons d'ajouter une URL **/helloworld** (tout comme il existe /post/...) à notre blog.

La fonction **register** de l'objet $core->url prend 4 paramètres :

  * Un **type,** sorte d'identifiant unique de l'URL.
  * La **forme de base de l'URL** que l'on peut obtenir par $core->url->getBase(<url>).
  * Une **expression rationnelle** permettant à l'interface publique de savoir quand réagir.
  * La **fonction** à appeler quand l'URL est reconnue. Cet argument peut-être n'importe quoi du moment qu'il s'agit d'une [[http://www.php.net/manual/fr/language.pseudo-types.php#language.types.callback|déclaration de callback valide]]. 

Dans le cas qui nous intéresse, nous disons à Dotclear d'appeler la méthode statique HelloWorld de la class HelloURL quand il reconnaît l'URL **/helloworld** sur le blog. L'URL en question a le type helloworld? et pourra être obtenue par **$core->url->getType('helloworld')**.

La méthode HelloWorld de la class HelloURL prend un seul argument : $args. Celui-ci contient l'éventuelle capture de l'expression rationnelle passée dans la définition de l'URL. Ici nous n'en avons pas, nous n'utilisons donc pas cet argument.

La méthode en elle-même est très simple, elle se contente de créer une page de type //text/plain// contenant les mots //Hello World//.

<note>
La class HelloURL hérite de dcUrlHandlers. Dans notre cas, ce n'était pas nécessaire mais vous pouvez en avoir besoin si par exemple vous souhaitez envoyer une page d'erreur 404. Il suffirait alors d'appeler self::p404() pour obtenir immédiatement une page d'erreur 404 avec les bons en-têtes HTTP et le template correspondant.
</note>

Dans votre navigateur, il vous suffit de saisir : **http://<url_du_site>/index.php?helloworld**

Votre plugin fonctionne ? Bravo ! Nous allons maintenant voir comment lui apporter quelques améliorations. [[admin|Création d'une page d'administration d'un plugin]]