J'ai choisi de reprendre le nom de l'ancien plugin qui fournissait la coloration syntaxique ,SyntaxeHl pour syntaxe highlight je présume.

Un répertoire avec GeShi pour le plugin

La première étape, très simple, consiste à créer un répertoire pour accueillir les fichiers de votre plugin. Pour cela, il suffit de créer un sous répertoire dans le répertoire plugins de votre Dotclear. Nommons le par exemple syntaxehl. Il vous faudra ensuite télécharger la dernière version de GeShi. Décompressez l'archive que vous venez de récupérer dans le répertoire que vous venez de créer. Ainsi vous devez obtenir un nouveau répertoire /plugins/syntaxehl/geshi/. Dans ce répertoire, vous pouvez supprimer les répertoires contrib et doc qui ne nous serons pas utile.

Informations relatives au plugin

Nous allons maintenant définir les différentes informations relatives à notre plugin. Pour cela, vous devez créer un fichier _define.php dans le répertoire /plugins/syntaxehl/. Le contenu de ce fichier sera le suivant :

<?php
$this->registerModule(
  /* Name */          "SyntaxeHl",
  /* Description*/    "Plugin de coloration syntaxique",
  /* Author */        "Votre Nom",
  /* Version */       '1',
  /* Permissions */   'usage,contentadmin'
);
?>

Les commentaires accompagnant chacun des paramètres sont suffisamment clair pour comprendre de quoi il s'agit. Nous ne nous arrêterons que sur le champ concernant les permissions. Il s'agit ici de définir quel type d'utilisateur peut activer le plugin. Dans cet exemple, nous avons choisit d'autoriser tous les utilisateurs mais on aurait également pu se limiter aux administrateurs en indiquant seulement admin.

Enregistrez les modifications puis rendez vous sur la page listant les plugin installés sur votre blog. Vous constaterez avec joie que le plugin que vous venez de créer apparaît bien dans la liste. Pour l'instant, ce plugin est totalement inutile puisqu'il ne fait absolument rien. Nous allons donc lui ajouter ses fonctionnalités.

Intercepter le code à mettre en forme

Pour mettre en forme le code inséré dans un billet, j'ai choisi d'exploiter la classe wiki2xhtml qui est employée, comme son nom l'indique, pour transformer la syntaxe Wiki d'un billet en (X)HTML.Ce choix peut être discutable puisqu'il ne permet pas de mettre en forme du code inséré dans un billet écrit directement en HTML.Cela-dit, je part du principe qu'un billet écrit en HTML directement ne devrait pas faire l'objet de modifications par un plugin puisqu'en principe il est déjà écrit dans sa version finale.

Pour mettre en forme les codes sources, nous allons exploiter une des fonctionnalités offertes par wiki2xhtml : les macros. Pour cela, nous utiliserons la fonction registerFunction de wiki2xhtml qui attend deux paramètres : le type de fonction que l'on souhaite enregistrer et la fonction en question. Pour le type, on indiquera simplement macro:nom_de_la_macro. Le fait d'enregistrer une fonction en tant que macro va déclencher l'appel à notre fonction lorsque la classe rencontrera dans le contenu du billet le texte suivant :

///nom_de_la_macro
du texte
///

Ici, notre fonction recevra du texte en paramètre, il nous suffira alors d'effectuer toutes les modifications souhaitées puis de retourner la version modifié du texte pour qu'elle remplace l'originale.

Enregistrer notre macro pour wiki2xhtml

Nous n'avons pour le moment qu'un bout de la solution finale. En effet, même si on sait comment procéder pour obtenir le code à mettre en forme, on ne sait pas vraiment comment procéder pour enregistrer notre fonction auprès de la classe wiki2xhtml aux bons moments.

Le système des behavior

Depuis la version 2, Dotclear intègre un tout nouveau système : les behavior. Terme qui peut être traduit littéralement par comportement. C'est un système très simple à utiliser qui propose une gestion événementielle. En fait, un plugin peut enregistrer une fonction pour tel ou tel événement. Lorsque cet événement se produit, Dotclear appel la ou les fonctions qui ont été enregistrées pour cet événement. En plus, ces fonctions recevront un certain nombre de paramètres différents en fonction du behavior concerné.

Parmi la liste des behavior diponibles, on trouve coreWikiPostInit qui est appelé lors de l'initialisation de la classe wiki2xhtml. La fonction qui sera enregistrée pour cette événement recevra une référence vers l'instance de wiki2xhtml en paramètre. Il sera donc très facile d'y enregistrer notre macro.

Quelques fichiers

Nous avons toutes les solutions en main pour la création de notre plugin. Nous allons maintenant pouvoir entamer le codage. Il faudra bien sur placer notre code dans certains fichiers. Comme vous pouvez l'imaginer, le fait de créer un fichier nommé n'importe comment ne sera pas forcément pris en compte par Dotclear. Le nommage est important pour le bon fonctionnement de notre plugin.

Ce qui va déterminer le nom du fichier que nous allons utiliser, c'est la partie de Dotclear dans laquelle on souhaite agir, la partie publique ou la partie administration. Pour agir sur la partie publique, on créera un fichier nommé _public.php ou alors un fichier _admin.php pour agir dans la partie administration.

Pour notre pugin, c'est dans la partie admin que nous voulons agir. En effet, les billets rédigés en syntaxe Wiki sont transformés en (X)HTML dans la partie administration. Nous allons donc créer un fichier _admin.php dans le répertoire /plugins/syntaxehl/.

Codage du plugin

Il ne nous reste maintenant plus qu'à coder notre plugin. Placez le code suivant dans le fichier _admin.php que nous venons de créer.

<?php
// Protège contre les accès directes au fichier
if (!defined('DC_CONTEXT_ADMIN')) exit;
 
// Require façon Dotclear
require(dirname(__FILE__).'/geshi/geshi.php');
 
// On enregistre notre behavior
$core->addBehavior('coreInitWikiPost',array('syntaxeHl','registerFunc'));
 
 
class syntaxeHl
{
        // Fonction correspondant à notre behavior
        public static function registerFunc(&$wiki2xhtml)
        {
                // On lit de répertoire de GeShi pour connaître
                // la liste des langages diponibles
                $dir = dirname(__FILE__).'/geshi/geshi/';
                $od = opendir($dir);
                while($f = readdir($od))
                {
                        // Si c'est bien un fichier portant l'extension .php
                        if(is_file($dir.$f) && substr($f,-4,4)=='.php')
                        {
                                // On enregistre une nouvelle macro pour ce langage
                                $lang = str_replace('.php','',$f);
                                $wiki2xhtml->registerFunction('macro:['.$lang.']',array('syntaxeHl','parse'));
                        }
                }
        }
 
        // Fonction appelée par Wiki2Xhtml
        public static function parse($text,$args)
        {
                // On supprime les caractères blancs en
                // en début et fin de chaîne (optionnel)
                $text = trim($text);
 
                // Création d'une instance de GeShi
                $geshi =& new GeSHi($text,$args);
 
                // On désactive les liens sur les mots clés (optionnel)
                $geshi->enable_keyword_links(false);
 
                // On retourne le code mis en forme, coloré
                return $geshi->parse_code();
        }
}
?>

Ayant déjà bien expliqué les solutions employées ci-dessus, je ne m'attarderais pas sur ce code. Vous pouvez consulter la documentation de Dotclear pour en savoir plus sur les méthodes utilisées.

Notez simplement que l'on utilise pas directement le nom du langage pour nommer nos macro, mais qu'on le place entre crochets ([ et ]). Il y a deux raisons à cela, d'une part le plugin qui assurait la coloration syntaxique pour Dotclear 1 utilisait lui aussi les crochets (rétro compatibilité) et d'autre part cela permet de ne pas interférer avec d'autres macros comme html par exemple qui permet d'insérer du code html dans un billet lorsqu'on est en syntaxe Wiki.

Un test ?

Si vous avez correctement suivit cet article, votre plugin est maintenant fonctionnel. Vous pouvez le tester en créant un nouveau billet et en insérant le code suivant (en syntaxe Wiki):

///[php]
<?php
  echo 'Hello world!';
?>
///

et vous obtiendrez normalement le résultat suivant :

<?php
  echo 'Hello world!';
?>

Vous remarquerez peut-être que ce plugin n'est pas rétro actif, c'est à dire que les anciens billets contenant du code sources ne seront pas colorés. Pour chacun d'entre eux, il vous faudra les éditer et enregistrer les modifications.

Packager votre plugin

Maintenant que votre plugin fonctionne, il pourrait être intéressant de le distribuer. Le meilleur moyen pour cela est de créer un package. Le moyen le plus simple est d'utiliser le plugin Packager dont c'est la seule et unique fonction.

Version finale

Pour ceux qui souhaitent simplement installer ce plugin sur leur blog, vous pouvez consulter le dépôt de plugin de Code-Web.org où vous trouverez les paquets directement installables sur Dotclear. Si vous avez des questions qui concernent ce plugin, rendez-vous sur le billet traitant de la dernière version disponible.