Nomenclature des fichiers des plugins

Structure générale d'un plugin

ROOT :

_define.php : fichier de définition (nom, auteur, numéro de version) du plugin.
_install.php : appelé dès qu'un utilisateur se rend sur le tableau de bord via l'interface d'administration
_prepend.php : sera lu après la création des objets, mais avant l'affichage. Il sera lu en façade ainsi que dans l'administration du blog
_admin.php : ne sera lu que dans l'administration du blog.
_public.php : ne sera lu qu'en façade du blog.
_widgets.php : utilisé par _admin.php et _public.php dans le cadre de la mise à disposition de widget(s) par le plugin pour une utilisation en dehors de la sidebar avec le marqueur de template <tpl:Widget>.
_xmlrpc.php : interface xmlrpc du plugin.
_services.php : contiendra tous les services Ajax utilisés par le plugin
index.php : contiendra la page d'administration du plugin.
style.css : contiendra les éventuelles règles CSS du plugin
icon.png : l'icône du plugin.
inc : dossier qui contiendra les sous dossiers et fichiers inclus nécessaires au fonctionnement du plugin
locales : dossier qui contiendra les sous dossiers de traduction.
- fr : dossier qui contiendra les fichier *.po de localisation pour le français
- en : dossier qui contiendra les fichier *.po de localisation pour l'anglais (facultatif car les plugins sont déjà en anglais)
- …
js : dossier qui contiendra les fichiers javascript nécessaires au fonctionnement du plugin
default-templates : dossier qui contiendra tous les fichiers *.html pour l'ajout de template

Note :

Chaque fichier *.php, *.js ou *.css doit comporter en entête, le bloc de la licence choisie pour distributer le plugin. Si aucune licence n'est présente, la propriété intellectuelle s’applique de la manière la plus restrictive et ne permet pas le réemploi/modification du code sans l’autorisation expresse de l’auteur.

Nomenclature des fichiers contenu dans le répertoire inc/

Lorsque vous créez une classe, veillez à ce qu'elle soit le plus explicite possible. Par exemple, un plugin dont le nom est « monSuperPlugin » utilise sa propre classe afin de définir un objet qui lui est propre. Le nom du fichier sera alors :

class.mon.super.plugin.php

Si votre classe étend des fonctions internes à Dotclear, on l'appellera une librairie. Par exemple, vous avez besoin de créer des listes dans l'administration du plugin « monSuperPlugin ». Le nom de la classe sera « monSuperPluginList » et le nom du fichier sera alors :

lib.mon.super.plugin.list.php

Pour charger ces classes, vous pouvez utiliser l'auto-chargement des classes de PHP, en plaçant ce code dans le fichier _prepend.php :

global $__autoload;
$__autoload['monSuperPlugin'] = dirname(__FILE__).'/inc/class.mon.super.plugin.php';

Vous pouvez aussi utiliser l'inclusion de fichiers :

require_once(dirname(__FILE__).'/inc/class.mon.super.plugin.php');

Protection des fichiers

Pour éviter que les fichiers PHP soient exécutés en dehors de Dotclear, on peut ajouter une vérification au début des fichiers.

Pour les fichiers lus seulement côté administration :

_admin.php
index.php
_install.php
_services.php
les fichiers contenant les classes utilisées dans l'administration

On ajoute le code suivant :

if (!defined('DC_CONTEXT_ADMIN')) {return;}

Pour les autres fichiers :

_define.php
_prepend.php
_public.php
_xmlrpc.php
les autres fichiers de classes

On ajoute :

if (!defined('DC_RC_PATH')) {return;}