Manuel de création de plugins pour Dotclear 2

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.

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.

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 :

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

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.

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

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.

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

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

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 :

<?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;
        }
}
?>

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

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. Création d'une page d'administration d'un plugin