Open Time

Pour développer un plugin Dotclear, il y a deux obligations :

1. Il faut qu’il soit dans un dossier spécifique, dont le nom est libre ; on choisira a11yConfig pour le notre^[1].
2. Il faut qu’il contienne un fichier particulier, à la racine de son dossier, nommé _define.php qui contient le minima pour que Dotclear le reconnaisse comme un plugin.

D’ailleurs, à peine avais-je créé et enregistré un contenu correct qu’il apparaissait dans la liste des plugins, même si à cet instant il ne sert strictement à rien :-)

Voilà le contenu du fichier _define.php :

<?php
/**
 * @brief a11yConfig, a plugin for Dotclear 2
 *
 * @package Dotclear
 * @subpackage Plugins
 *
 * @author Franck Paul, Biou and contributors
 *
 * @copyright Franck Paul carnet.franck.paul@gmail.com
 * @copyright GPL-2.0 https://www.gnu.org/licenses/gpl-2.0.html
 */

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

$this->registerModule(
    "a11yConfig",                                           // Name
    "Implements Access42 accessibility configuration tool", // Description
    "Franck Paul, Biou and contributors",                   // Author
    '1.0',                                                  // Version
    [
        'requires'    => [['core', '2.15']],
        'permissions' => 'admin',                                     // Permissions
        'type'        => 'plugin',                                    // Type
        'support'     => 'https://github.com/franck-paul/a11yConfig', // Support URL
        'settings'    => ['pref' => '#user-options.a11yConfig']      // Settings
    ]
);

On va maintenant prendre le temps d’expliquer son contenu.

Ligne 1, le début de tout fichier en PHP

Ligne 2 à 12, du bla bla en commentaire pour expliquer un peu de quoi il retourne, avec quelques mots clés qui sont reconnus par les générateurs de documentation, comme Doxygen, qu’on utilise pour Dotclear et Clearbricks^[2].

Ligne 14, une petite protection pour éviter que ce fichier soit inclus n’importe comment.

Ligne 16 à 28, un appel de fonction qui permet d’enregistrer notre plugin dans la liste des plugins gérés par Dotclear. On va détailler cette partie un peu plus.

Cette fonction, registerModule attend 5 paramètres. On retrouve les 4 premiers respectivement dans les lignes 17 à 20, avec :

1. Le nom du plugin, qui peut reprendre le même nom que le dossier, c’est souvent plus pratique, mais j’aurais tout aussi bien pu utiliser Access42 config tool, par exemple.
2. Une description succincte de ce qu’il fait — en anglais, on verra plus tard comment fournir une traduction, comme pour le nom ci dessus d’ailleurs.
3. La liste des auteurs et contributeurs
4. Son numéro de version qui sera incrémenté du côté décimal pour chaque version de correction de bug et du côté ordinal pour les versions majeures, celles qui apportent de nouvelles fonctionnalités, par exemple.

Enfin, le 5e paramètre, qui est un tableau de propriétés et qui permet de définir quelques particularités. Détaillons chacune de ses lignes, sachant qu’il pourra être complété dans le futur en fonction des besoins^[3] :

1. requires permet de définir les versions minimum de Dotclear et/ou de certains plugins pour que le notre puisse fonctionner. Comme on va utiliser des fonctionnalités présentes depuis la version 2.15 seulement, j’ai indiqué que je voulais a minima la version 2.15 de Dotclear.^[4]
2. permissions permet de définir le droits minimum attendus pour qu’on puisse gérer ce plugin. Si ce paramètre est absent alors seuls les super-administrateurs pourront le gérer. Notez qu’une fois réglé par un administrateur ou super-administrateur, ça n’empêche en rien son usage côté public. Pour l’instant j’ai spécifié admin, mais il faudra peut-être y revenir pour autoriser son usage côté administration du blog et utiliser alors la valeur usage. On verra le moment venu.
3. type permet de spécifier que c’est un plugin, pour les thèmes, qui ont également un fichier identique à la racine de leur propre dossier, on spécifiera theme. Notez que cette propriété est indispensable pour le plugin soit reconnu comme tel, sinon il sera simplement ignoré.
4. support permet d’indiquer une URL de support. Ici j’ai choisi le dépôt Github que je viens de créer pour l’occasion et sur lequel vous pourrez contribuez si vous le désirez, en créant des tickets ou en proposant des modifications et ajouts dans le code.
5. settings permet d’indiquer les différents endroits, dans la partie administration des blogs, où ce plugin peut être configuré, en plus de sa page principale. Ici, comme on envisage d’appliquer cet outil du côté administration du blog, et que ça concerne l’utilisateur, on fera ça dans « Mes préférences », d’où la clé pref, la valeur #user-options.a11yConfig permet d’indiquer que c’est le 2e onglet de la page qui servira (« Mes options ») et que ça se passera dans une boîte qu’on référencera avec a11yConfig (on y reviendra le moment venu).

Voilà pour aujourd’hui, c’est déjà assez copieux !