Développer un plugin, on prévoit l'activation

On continue notre petit développement et on va s’occuper maintenant de l’option qui permet d’activer, côté public, le plugin. Il est en effet d’usage de prévoir, sauf cas particulier, blog par blog, l’activation à la demande d’une nouvelle fonctionnalité.

Pour faire ça, plusieurs choses :

Prévoir une page avec un formulaire pour activer et désactiver le plugin ; au passage on fera en sorte d’enregistrer l’état par défaut si ce n’est pas déjà fait.
Ajouter une entrée dans le menu Blog de l’administration pour atteindre cette page.

Notez que j’aurais aussi bien pu ajouter ce réglage dans les paramètres du blog, dans la section « Paramètres des plugins pour ce blog ». On verra la prochaine fois comment faire ça. Ça sera certes redondant avec ce qu’on développe aujourd’hui mais au moins on sera exhaustif :-)

Donc, commençons par créer un fichier index.php qui gèrera le formulaire d’activation (et prochainement les options associées) du plugin.

Le code est le suivant et je vais le détailler :

<?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_CONTEXT_ADMIN')) {return;}

$core->blog->settings->addNamespace('a11yConfig');
if (is_null($core->blog->settings->a11yConfig->active)) {
    try {
        // Add default settings values if necessary
        $core->blog->settings->a11yConfig->put('active', false, 'boolean', 'Active', false);
        $core->blog->triggerBlog();
        http::redirect($p_url);
    } catch (Exception $e) {
        $core->error->add($e->getMessage());
    }
}

// Get current options
$ac_active = (boolean) $core->blog->settings->a11yConfig->active;

if (!empty($_POST)) {
    try
    {
        $ac_active = !empty($_POST['ac_active']);

        # Everything's fine, save options
        $core->blog->settings->addNamespace('a11yConfig');
        $core->blog->settings->a11yConfig->put('active', $ac_active);

        $core->blog->triggerBlog();

        dcPage::addSuccessNotice(__('Settings have been successfully updated.'));
        http::redirect($p_url);
    } catch (Exception $e) {
        $core->error->add($e->getMessage());
    }
}

?>
<html>
<head>
  <title><?php echo __('a11yConfig'); ?></title>
</head>

<body>
<?php
echo dcPage::breadcrumb(
    [
        html::escapeHTML($core->blog->name) => '',
        __('a11yConfig')                    => ''
    ]);
echo dcPage::notices();

echo
'<form action="' . $p_url . '" method="post">' .
'<p>' . form::checkbox('ac_active', 1, $ac_active) . ' ' .
'<label for="ac_active" class="classic">' . __('Active a11yConfig') . '</label></p>' .
'<p>' . $core->formNonce() . '<input type="submit" value="' . __('Save') . '" /></p>' .
    '</form>';

?>
</body>
</html>

Je passe les premières lignes (1 à 13) qui devraient vous être familières et qui sont répétées d’un fichier PHP à un autre du plugin.

La ligne 14 permet de s’assurer que ce fichier est bien utilisé (inclus) dans le contexte d’administration du ou des blogs de l’installation.

Les lignes 16 à 26 permettent d’enregistrer, si ce n’est pas déjà fait (voir le test ligne 17), l’option par défaut, c’est-à-dire la non-activation du plugin pour le blog sélectionné. Une autre façon de faire serait d’utiliser un fichier _install.php chargé d’enregistrer la valeur par défaut de façon globale. Je détaillerai ça ensuite dans ce billet.

La ligne 29 permet de récupérer la valeur actuellement enregistrée pour le blog.

Les lignes 31 à 47 permettent de gérer la soumission du formulaire et par conséquent l’enregistrement de l’option choisie pour le blog actif.

Enfin les lignes 50 à 73 permettent de définir le contenu de la page et du formulaire qui s’y trouve.

Voilà à quoi ressemble le formulaire une fois celui-ci affiché :

Comme promis ci-dessus, voyons comment enregistrer une valeur par défaut globale pour l’activation, valeur qui sera utilisée tant qu’on ne l’aura pas explicitement modifiée pour le blog sélectionné.

Le fichier qui gère ça, se nomme _install.php et il permet, à chaque installation et mise à jour du plugin, d’effectuer un certain nombre d’actions. Voyons son contenu (il sera peut-être amené à être complété si besoin dans le futur) :

<?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_CONTEXT_ADMIN')) {return;}

$new_version = $core->plugins->moduleInfo('a11yConfig', 'version');
$old_version = $core->getVersion('a11yConfig');

if (version_compare($old_version, $new_version, '>=')) {
    return;
}

try
{
    $core->blog->settings->addNamespace('a11yConfig');
    $core->blog->settings->a11yConfig->put('active', false, 'boolean', 'Active', false, true);

    $core->setVersion('a11yConfig', $new_version);

    return true;
} catch (Exception $e) {
    $core->error->add($e->getMessage());
}
return false;

Je passe les premières lignes (1 à 13), c’est comme d’habitude. La ligne 14 est toujours celle qui permet d’assurer que ce fichier est bien utilisé dans un contexte d’administration ; on l’a vu pour le fichier index.php ci-dessus.

Les lignes 16 à 21 permettent de tester si la version actuelle du plugin n’a pas changé. Si c’est le cas, inutile d’aller plus loin et on rend la main à Dotclear.

Dans le cas contraire, on a donc une version actuelle du plugin plus récente que celle qu’on a enregistrée à la dernière installation ou mise à jour, on continue en enregistrant la valeur par défaut de l’option d’activation du plugin (lignes 25 et 26), puis on enregistre la version actuelle du plugin (ligne 28).

On a donc, jusque là, une page pour gérer l’activation du plugin pour le blog actif (index.php) et de quoi enregistrer la valeur par défaut valable pour tous les blogs de la plateforme (_install.php).

D’ailleurs, lorsqu’on liste les plugins installés, on peut constater que Dotclear a détecté la présence de la page de réglage et indique un lien pour y accéder :

Voyons maintenant comment ajouter un accès direct dans le menu Blog pour permettre l’activation de ce plugin d’une manière plus rapide.

Pour ça, il faut prévoir un fichier _admin.php dont le contenu est le suivant :

<?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_CONTEXT_ADMIN')) {return;}

$_menu['Blog']->addItem(__('a11yConfig'), 'plugin.php?p=a11yConfig', urldecode(dcPage::getPF('a11yConfig/icon.png')),
    preg_match('/plugin.php\?p=a11yConfig(&.*)?$/', $_SERVER['REQUEST_URI']),
    $core->auth->check('admin', $core->blog->id));

Je ne détaille pas les lignes 1 à 14, c’est comme auparavant.

La ligne 16 permet de définir l’entrée de menu correspondante à notre plugin en vérifiant au passage qu’on a les droits d’administration sur le blog activé (dernier paramètre de l’appel). En effet seul l’administrateur du blog (ou un super-administrateur) peut activer ou désactiver son fonctionnement. Pas question de laisser cet accès aux rédacteurs lambdas de la plateforme.

Vous voyez que j’ai également prévu une icône pour le plugin, afin que celle-ci « décore » l’entrée de menu :

Je vais terminer pour aujourd’hui en prenant soin de relancer l’outil de génération des traductions française pour obtenir un formulaire affiché en français. Reportez-vous au billet précédent pour les détails.

En effet il y a quelques libellés « nouveaux » dans le formulaire et au moins l’un d’entre eux est spécifique à ce plugin et à besoin d’une traduction.

On va s’arrêter là pour aujourd’hui et n’hésitez pas à me poser vos questions ou à me faire des remarques sur le contenu de cette série et de ses billets dans les commentaires de ce billet (ou des autres d’ailleurs), en particulier si vous souhaitez que je sois plus précis et/ou technique dans mes explications.

4 réactions

Fil des commentaires de ce billet

1 De Bernard - 25/11/2019, 16:08

Oups 3 fichiers d’un coup ;-)
Pour info, on peut se référer à la documentation Dotclear qui - même si elle est un peu “ancienne”, permet de suivre quant au fonctionnement d’un plugin et, particulièrement, à propos de la “fonction” des différents fichiers qui peuvent le structurer.

Sinon je suppose que la ligne 34 (ci-dessous) du fichier index.php
$ac_active = !empty($_POST['ac_active']);
ne peut s’appliquer qu’à une valeur booléenne puisqu’elle “stocke” dans $ac_active, true ou false suivant le résultat non vide ou vide (!empty) de la case à cocher ‘ac_active’ du formulaire
2 De Franck - 25/11/2019, 16:25

Tu supposes correctement Bernard :-)
3 De Bernard - 24/12/2019, 17:46
Par habitude, et au kazoo il s’avérerait de modifier l’install du plug en cours de développement afin de ne pas modifier la valeur de la version j’ai inséré la ligne return; entre commentaires.
```
//*/ uncomment to update
   return;
//*/
```
chai po si c’est une bonne pratique, mais j’ai souvent utilisé cette méthode quand je tentais de corriger des erreurs sur des plugs…
4 De Franck - 25/12/2019, 10:05

On peut aussi imaginer d’utiliser la constante DC_DEBUG prévue pour ce genre d’usage ;-)

Open Time

Développer un plugin, on prévoit l'activation

4 réactions

Ajouter un commentaire

Ajouter un rétrolien