Open Time

Aujourd’hui on va voir comment implémenter l’activation à partir des paramètres du blog plutôt qu’à partir d’une page dédiée. En fait on va conserver les deux, aux fins de démonstration mais dans l’absolu il n’est pas utile de faire les deux.

D’un point de vue pragmatique, si vous avez uniquement besoin d’autoriser les réglages du plugin par l’administrateur du blog ou par un super-administrateur, alors il est probablement plus simple de faire ça dans les paramètres du blog, dans la section « Paramètres des plugins pour ce blog ».

Par contre, si vous envisagez d’autoriser le réglage à d’autres alors il est impératif de prévoir une page dédiée (fichier index.php) pour permettre son accès. D’autre part, si les paramètres du plugin sont nombreux, il est aussi probablement préférable de prévoir une page dédiée.

Avant de rentrer dans le détail du code nécessaire pour intégrer ces réglages du côté des paramètres du blog, une petite explication à propos des behaviors. Il s’agit d’un système, prévu dans Dotclear, qui permet d’ajouter un ou plusieurs traitements supplémentaires lorsqu’un événement est déclenché.

Pour cela, on code le traitement supplémentaire nécessaire puis on l’enregistre dans Dotclear pour l’événement correspondant. C’est ce qu’on va voir maintenant en pratique.

Pour ajouter un « bloc » de réglage aux paramètres du blog, il faut prévoir deux traitements qui seront appelés sur deux événements particuliers :

1. Le premier événement (ou behavior) est adminBlogPreferencesForm qui est déclenché lorsque la page des paramètres du blog est en cours de construction, avant son affichage.
2. Le deuxième événement est adminBeforeBlogSettingsUpdate qui est déclenché juste avant que Dotclear enregistre les paramètres du blog (lorsqu’on appuie sur la touche Enregistrer en bas de page).

Voilà le code associé aux deux événements, en commençant par la construction du bloc de réglage :

public static function adminBlogPreferencesForm($core, $settings)
{
    echo
    '<div class="fieldset"><h4 id="a11yc_prefs">' . __('a11yConfig') . '</h4>' .
    '<p>' . form::checkbox('a11yc_active', 1, $settings->a11yConfig->active) . ' ' .
    '<label for="a11yc_active" class="classic">' . __('Active a11yConfig') . '</label></p>' .
    '</div>';
}

Puis le second pour enregistrer les réglages du plugin, pour l’instant son état d’activation :

public static function adminBeforeBlogSettingsUpdate($settings)
{
    $settings->a11yConfig->put('active', !empty($_POST['a11yc_active']), 'boolean');
}

Ensuite il faut « enregistrer » ces traitements pour qu’ils soient effectivement appelés lorsque les événements correspondants sont déclenchés.

Cet enregistrement se fait dans le fichier _admin.php puisqu’il s’agit d’événement d’administration. S’il s’agissait d’événements publics, on aurait alors fait l’enregistrement dans le fichier _public.php (qui n’existe pas encore à cette étape du développement).

Voilà les deux lignes que j’ai ajoutées à la fin du fichier _admin.php :

$core->addBehavior('adminBlogPreferencesForm', ['a11yconfigAdminBehaviors', 'adminBlogPreferencesForm']);
$core->addBehavior('adminBeforeBlogSettingsUpdate', ['a11yconfigAdminBehaviors', 'adminBeforeBlogSettingsUpdate']);

Le premier paramètre fourni à la fonction addBehavior() est le nom de l’événement, le deuxième paramètre est la fonction (associée à sa classe) qui sera exécutée lorsque cet événement est déclenché.

Vous remarquerez que j’utilise une classe nommée a11yconfigAdminBehaviors soit celle que j’ai utilisée pour « encadrer » mes deux fonctions. Voilà le code complet de la classe proprement dite (qui reprend les deux premiers codes de ce billet) :

<?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;}
// public

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

class a11yconfigAdminBehaviors
{
    public static function adminBlogPreferencesForm($core, $settings)
    {
        echo
        '<div class="fieldset"><h4 id="a11yc_prefs">' . __('a11yConfig') . '</h4>' .
        '<p>' . form::checkbox('a11yc_active', 1, $settings->a11yConfig->active) . ' ' .
        '<label for="a11yc_active" class="classic">' . __('Active a11yConfig') . '</label></p>' .
            '</div>';
    }

    public static function adminBeforeBlogSettingsUpdate($settings)
    {
        $settings->a11yConfig->put('active', !empty($_POST['a11yc_active']), 'boolean');
    }
}

Cette classe a été enregistrée dans un fichier a11yconfig.behaviors.php que j’ai placé dans un répertoire inc que j’ai créé pour l’occasion (voir ce billet pour plus de détail sur l’architecture des dossiers et fichiers d’un plugin).

L’enregistrement tel que je l’ai fait ne suffit pas.

En effet, Dotclear, à ce stade, ne sait pas où est « rangé » le code des deux traitements. Pour cela il faut créer un nouveau fichier, à la racine du plugin, nommé _prepend.php, qui permet de définir l’endroit où sont « rangées » notre ou nos classes de code. Voilà son contenu :

<?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;}
// public

if (!defined('DC_CONTEXT_ADMIN')) {return false;}
// admin

$__autoload['a11yconfigAdminBehaviors'] = dirname(__FILE__) . '/inc/a11yconfig.behaviors.php';

C’est la dernière ligne qui permet de faire la « liaison » entre la classe a11yconfigAdminBehaviors et son emplacement physique dans le fichier /inc/a11yconfig.behaviors.php.

Au passage vous remarquerez la ligne 14, qui permet comme à d’autres endroits, d’éviter l’inclusion de ce fichier n’importe comment — on l’a déjà évoquée dans nos billets précédents — et plus spécialement la ligne 17 qui arrête la lecture du code du fichier si on n’est pas dans un contexte d’administration.

En effet, ce fichier _prepend.php est appelé quel que soit le contexte, public ou administration ; il est donc utile d’éviter l’exécution de code superflu (on considère que le contexte d’administration est un « sur-ensemble » du contexte public).

Maintenant, une fois tout ce « nouveau » code écrit, on peut constater qu’un nouveau « bloc » de réglage apparaît dans les paramètres du blog :

Nous voilà donc avec deux endroits pour activer ou désactiver ce plugin pour le blog actif.

D’ailleurs, afin d’être exhaustif nous allons ajouter une indication dans le fichier _define.php pour préciser où se trouve ce nouveau réglage :

<?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'    => [
            'blog' => '#params.a11yc_prefs',
            'pref' => '#user-options.a11yConfig'] // Settings
    ]
);

C’est la ligne 27 qui nous intéresse et qui fait référence à l’onglet « Paramètres » (#params) de la page des « Paramètres du blog » et au bloc de réglage de notre plugin dans lequel j’ai pris soin d’affecter un identificateur HTML, sur la balise H4 (voir le premier code de ce billet), pour pouvoir y accéder directement (.a11yc_prefs).

D’ailleurs, lorsqu’on consulte la page de gestion des plugins, ce nouveau lien est affiché :

Un clic sur celui-ci vous mènera directement au bloc correspondant.