Les plugins DotClear permettent d'ajouter facilement des fonctions supplémentaires à votre blog. Par exemple, un plugin peut servir à réaliser des opérations massives sur la base de données ou encore s'occuper de la gestion des fichiers de votre installation, etc.
Par ailleurs, un plugin peut également interagir avec la partie publique de votre blog par le biais de fonctions que vous aurez prédéfinies.
Faire un plugin n'est pas très compliqué, il suffit de connaître PHP.
Les plugins sont tous situés dans le repertoire ecrire/tools/ de votre installation. Nous allons voir comment est construit un plugin type pour DotClear, appelons le monplugin.
Voici la structure minimale d'un plugin :
monplugin/
Ce fichier est un fichier XML permettant de décrire le plugin. Il sera utilisé par la page d'affichage des plugins et par le gestionnaire des plugins.
Voici comment est fait le fichier desc.xml :
<?xml version="1.0" encoding="ISO-8859-1"?> <plugin name="monplugin" version="0.5" active="1"> <author>Me</author> <label>My plugin</label> <desc>This is my first plugin!</desc> </plugin>
Voici à quoi correspondent les éléments XML du plugin :
Notez bien que les informations doivent de préférence être rédigées en anglais et que l'encoding doit impérativement être ISO-8859-1. Nous verrons plus tard comment ces informations peuvent être automatiquement traduites.
Ce fichier est une image au format PNG de taille 32 pixels par 32. Évitez d'utiliser la transparence alpha sur cette image, Internet Explorer la gérant très mal.
Si vous n'avez aucun talent pour faire des icônes, vous trouverez peut-être votre bonheur sur le site de Jakub 'jimmac' Steiner.
Si ce fichier existe, il sera alors utilisé dans l'interface d'administration de DotClear, à côté du nom et de la description de votre plugin.
C'est le fichier principal de votre plugin. Quelques règles doivent être suivies pour sa conception :
Vous pouvez utiliser toutes les fonctions PHP que vous souhaitez à l'exception de toutes les fonctions affichant directement des valeurs, comme echo, print, printf, etc.
Tout le code HTML résultant de ce fichier devra donc être affiché avec la fonction buffer::str($chaine); où $chaine est la chaîne de caractères que vous souhaitez afficher.
Le premier niveau de titre d'un plugin est <h2>.
Voici un exemple du fichier index.php de votre premier plugin :
<?php buffer::str('<h2>Mon premier plugin</h2>'); buffer::str('<p>'); for ($i=1; $i<=10; $i++) { buffer::str($i.'<br />'); } buffer::str('</p>'); ?>
Votre premier plugin affiche une suite de 1 à 10, passionant !
Faire un plugin entièrement en français est une mauvaise idée pour deux raisons. D'une part, il sera impossible de le rendre disponible à des personnes ne comprenant pas le français et, plus grave, dans un blog configuré en UTF-8, tous les caractères accentués seront remplacés par des signes cabalistiques de très mauvais goût.
Bien sûr, vous ne voulez pas cela ! Voyons comment traduire votre plugin.
Votre plugin va donc être entièrement en anglais et nous proposerons une localisation en français.
La première chose à faire consiste à créer un répertoire l10n dans votre plugin, si ce n'est déjà fait. Ajoutez-y ensuite un répertoire fr dans lequel vous créerez un fichier main.lang. C'est ce fichier qui va servir à traduire notre plugin en français.
Commençons par traduire les chaînes de caractères se trouvant dans le fichier desc.xml, nous verrons ainsi comment est structuré un fichier de langue:
;My plugin Mon plugin ;This is my first plugin! Ceci est mon premier plugin !
Je pense que vous avez compris comment est fait un fichier de langue quelques règles essentielles :
Avec un tel fichier, vous constaterez que le titre et la description de votre plugin sont traduits sur la page listant les outils.
Dans notre fichier index.php nous avions une chaîne en français, voyons comment la traduire elle aussi :
Dans le fichier de langue, ajouter le bloc suivant :
;My first plugin Mon premier plugin
Ensuite dans index.php, il suffit de remplacer la seconde ligne par celle-ci :
<?php buffer::str('<h2>'.__('My first plugin').'</h2>'); ?>
Vous l'aurez compris, la fonction __() est chargée de trouver la traduction d'une chaîne et de l'afficher.
Si votre blog est en UTF-8 vous aurez sans doute remarqué que toutes les manipulations décrites auparavant ne fonctionnent pas. Cessez de vous arracher les cheveux, la solution est simple.
Créez un nouveau répertoire de langue nommé cette fois fr-utf8 et copiez-y le fichier main.lang (avec son contenu). Ensuite enregistrez ce fichier au format UTF-8. Votre plugin doit maintenant être correctement traduit.
Si vous ne savez pas comment faire cette conversion, utilisez l'outil de conversion suivant et copiez le résultat dans votre fichier de langue UTF-8.
Votre plugin aura sans doute besoin d'accéder à la base de données de DotClear pour réaliser certaines opérations. Pour cela il dispose de deux objets importants : $blog et $con.
Cet objet est une instance de la classe blog dont vous trouverez les sources dans le fichier inc/classes/class.blog.php. Cet objet est une sorte de super intendant, gérant tout ce qui touche à votre blog. Lisez la documentation de la classe blog pour plus de détails.
Cet objet est une instance de la classe connection dont vous trouverez les sources dans le fichier inc/classes/class.mysql.php.
Il est en charge de tout ce qui est relatif à la base de données et permet entre autre de réaliser des requêtes SQL.
Voyons comment faire une requête sur la table contenant les billets et en afficher les résultats dans votre plugin.
<?php $rs = $con->select('SELECT post_id, post_titre FROM '.DB_PREFIX.'post LIMIT 0,5'); ?>
Cette requête va demander le post_id et le post_titre dans la table des billets et n'en prendre que 5.
La variable $rs resultante est un recordset que vous pouvez manipuler comme suit :
<?php while ($rs->fetch()) { buffer::str($rs->f('post_titre')); } ?>
Cela affichera les titres des billets les uns à la suite des autres.
Pour plus de détails, lisez les documentations de la classe connection et de la classe recordset.
Les plugins peuvent également servir à interagir avec la partie publique de votre blog. Pour cela vous devez créer un fichier functions.php à la raçine de votre plugin. Il sera alors automatiquement inclus à chaque appel de la page principale du weblog.
Vous créez n'importe quelle fonction dans ce fichier et ensuite l'appelez dans votre thème (dans le fichier template.php par exemple).
Voici l'exemple d'un fichier functions.php contenant une fonction permettant d'afficher le nombre de commentaires publiés sur le blog:
<?php class monPlugin { function nbComments() { global $blog; echo $blog->getNbComments(''); } } ?>
Vous remarquerez que nous avons mis la fonction dans une classe. Je vous conseille de procéder ainsi, cela évitera que vos fonctions entrent en conflit avec une fonction portant le même nom.
Pour appeler la fonction dans le fichier template.php, c'est très simple :
<p>Nombre de commentaires : <?php monPlugin::nbComments(); ?></p>
Les callbacks sont des fonctions propre à un plugin pouvant réagir à un événement (un billet est posté, publié, etc.). C'est un moyen commode pour étendre DotClear avec des fonctionnalités inédites.
Voici comment un callback peut-être ajouté à un plugin pour l'événement onCreatePost (un billet est créé). Dans le fichier desc.xml du plugin on ajoute l'appel à la fonction qui assurera le traitement de l'événement. Par exemple:
<plugin name="ping"> <!-- ... --> <callback event="onCreatePost" function="dcCbPing::pingSites"/> </plugin>
Cet appel indique que lorsque l'on crée un billet (premier enregistrement), la fonction statique pingSites de la classe dcCbPing est appelée.
La classe dcCbPing doit être définie dans un fichier events.php à la racine du plugin. La fonction doit être statique, la classe ne sera jamais instanciée. (Cela correspond à un appel classique dcCbPing::pingSites).
Les fonctions utilisées pour un callback doivent être des méthodes statique d'un classe se trouvant dans un fichier events.php à la racine du plugin. Le nom de la classe devra s'appeler dcCbnomDuPlugin.
Description : événement appelé lorsqu'un billet est enregistré pour la première fois.
Arguments de la fonction : &blog, objet blog passé par référence ; post_id, identifiant du billet nouvellement créé.
Description : événement appelé lorsqu'un billet est modifié.
Arguments de la fonction : &blog, objet blog passé par référence ; post_id, identifiant du billet modifié.
Description : événement appelé lorsqu'un billet est supprimé.
Arguments de la fonction : &blog, objet blog passé par référence ; post_id, identifiant du billet supprimé.
Description : événement appelé lorsqu'un commentaire est enregistré via la zone publique du blog.
Arguments de la fonction : &blog, objet blog passé par référence ; comment_id, identifiant du commentaire créé.
Description : événement appelé lorsqu'un commentaire est enregistré via la zone privée du blog.
Arguments de la fonction : &blog, objet blog passé par référence ; comment_id, identifiant du commentaire créé.
Description : événement appelé lorsqu'un commentaire (ou un trackback) est modifié.
Arguments de la fonction : &blog, objet blog passé par référence ; comment_id, identifiant du commentaire créé.
Description : événement appelé lorsqu'un trackback est enregistré.
Arguments de la fonction : &blog, objet blog passé par référence ; comment_id, identifiant du commentaire créé (un trackback est un commentaire).
Description : événement appelé lorsqu'un commentaire (ou trackback) est supprimé.
Arguments de la fonction : &blog, objet blog passé par référence ; comment_id, identifiant du commentaire supprimé.
Documentation des classes Dotclear
Si vous rencontrez des difficultés pour créer votre plugin, n'hésitez pas à poser vos questions sur le forum.