Guide de création des plugins
Introduction
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.
Un plugin type
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.
Structure des fichiers
Voici la structure minimale d'un plugin :
monplugin/ |- desc.xml |- icon.png |- index.php |- l10n/ | |- fr/ | | |- main.lang
Le fichier ''desc.xml''
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 :
<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 :
- plugin/name : Nom du plugin, uniquement des lettres ou des chiffres,
- plugin/version : numéro de version du plugin, à votre convenance,
- plugin/active : (O ou 1) indique si le plugin est activé,
- author : le nom de l'auteur du plugin,
- label : le titre du plugin,
- desc : description 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.
Le fichier ''icon.png''
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.
Le fichier ''index.php''
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 :
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 !
Localisation du plugin
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.
Les fichiers de traduction
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 :
- La chaîne originale commence par un point virgule (;).
- La traduction est sur la ligne immédiatement inférieure.
- Chaque chaîne est inscrite sur une seule ligne.
- Il n'est pas interdit de sauter des lignes entre chaque bloc de traduction.
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 :
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.
Cas particulier de l'UTF-8
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.
Accès à la base de données
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.
L'objet $blog
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.
L'objet $con
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.
$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 :
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.
Interaction avec la partie publique
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:
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 :
<?php monPlugin::nbComments(); ?></p>
Ressources
Si vous rencontrez des difficultés pour créer votre plugin, n'hésitez pas à poser vos questions sur le [http://www.dotclear.net/forum/viewforum.php?id=5
forum].
Classes nécessaires :
Commentaires