DotclearWatch / Blog - Mot-clé - structure

Fichier Install d'un module

Jean-Christian Denis — Sun, 16 Jul 2023 20:51:00 +0100

Le fichier Install.php, placé dans le dossier src du module, permet d'effectuer ses opérations d'installation et de mise à jour.

Le fichier Install.php fait partie du processus reconnu par le gestionnaire de modules, il est donc automatiquement pris en compte coté admin si il existe.

Il est placé dans le sous dossier src du module,
Il contient une classe du nom de Install,
Il est dans l'espace de nom PHP Dotclear\Plugin\monPlugin ou Dotclear\Theme\monTheme,
La classe doit étendre la classe Process,
Seules les méthodes init() et process() sont utilisées,

Ce fichier est chargé en préambule de la page d'accueil de l'admin, de la page de gestion de l'apparence du blog, et de la page de gestion des plugins. Généralement il permet d'enregistrer des paramètres, de créer des tables, etc.
La méthode init() de la classe doit vérifier que la version installée n'existe pas ou qu'elle est à mettre à jour, elle doit renvoyer false si il n'y a pas besoin d'effectuer ces opérations d'installation / mise à jour. Pour aider, la classe My embarque un contexte qui permet cela My::checkContext(My::INSTALL).

Exemple du plugin blogroll de la distribution qui ajoute une table à la base de données :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\blogroll;

use dcCore;
use Dotclear\Core\Process;
use Dotclear\Database\Structure;
use initBlogroll;

class Install extends Process
{
    public static function init(): bool
    {
        return self::status(My::checkContext(My::INSTALL));
    }

    public static function process(): bool
    {
        if (!self::status()) {
            return false;
        }

        $schema = new Structure(dcCore::app()->con, dcCore::app()->prefix);

        $schema->{initBlogroll::LINK_TABLE_NAME}
            ->link_id('bigint', 0, false)
            ->blog_id('varchar', 32, false)
            ->link_href('varchar', 255, false)
            ->link_title('varchar', 255, false)
            ->link_desc('varchar', 255, true)
            ->link_lang('varchar', 5, true)
            ->link_xfn('varchar', 255, true)
            ->link_position('integer', 0, false, 0)

            ->primary('pk_link', 'link_id')
            ->index('idx_link_blog_id', 'btree', 'blog_id')
            ->reference('fk_link_blog', 'blog_id', 'blog', 'blog_id', 'cascade', 'cascade')
        ;

        (new Structure(dcCore::app()->con, dcCore::app()->prefix))->synchronize($schema);

        return true;
    }
}

Le contenu de ce document a été écrit suivant le code de la version 2.27 de Dotclear.

Fichier Config d'un module

Jean-Christian Denis — Sun, 16 Jul 2023 14:03:00 +0100

Le fichier Config.php, placé dans le dossier src du module, simplifie la gestion de sa configuration.

Le fichier Config.php fait partie du processus reconnu par le gestionnaire de modules, il est donc automatiquement pris en compte dans l'administration si il existe.

Il est placé dans le sous dossier src du module,
Il contient une classe du nom de Config,
Il est dans l'espace de nom PHP Dotclear\Plugin\monPlugin ou Dotclear\Theme\monTheme,
La classe doit étendre la classe Process,
Les 3 méthodes init() et process() et render() sont utilisées,

Cette classe simplifie la gestion de la configuration d'un module dans le sens où la partie construction de la page est déjà effectuée par le gestionnaire de modules. Seul le traitement des valeurs et le contenu du formulaire sont à la charge de la classe Config. Un lien vers cette page sera ajouté à la liste de plugins ou sur les thèmes de la page de gestion d'apparence du blog. Un lien sera également ajouté en bas de page principale de gestion du plugin si elle existe.

Exemple complet du fichier config du thème customCSS de la distribution :

<?php
namespace Dotclear\Theme\customCSS;

use dcCore;
use Dotclear\Core\Backend\Notices;
use Dotclear\Core\Process;
use Dotclear\Helper\File\Path;
use Dotclear\Helper\Html\Html;
use Dotclear\Helper\L10n;
use Exception;
use form;

class Config extends Process
{
    public static function init(): bool
    {
        if (My::checkContext(My::CONFIG)) {
            My::l10n('main');
            dcCore::app()->admin->css_file = Path::real(dcCore::app()->blog->public_path) . '/custom_style.css';

            if (!is_file(dcCore::app()->admin->css_file) && !is_writable(dirname(dcCore::app()->admin->css_file))) {
                throw new Exception(
                    sprintf(
                        __('File %s does not exist and directory %s is not writable.'),
                        dcCore::app()->admin->css_file,
                        dirname(dcCore::app()->admin->css_file)
                    )
                );
            }
            self::status(true);
        }

        return self::status();
    }

    public static function process(): bool
    {
        if (!self::status()) {
            return false;
        }

        if (isset($_POST['css'])) {
            @$fp = fopen(dcCore::app()->admin->css_file, 'wb');
            fwrite($fp, $_POST['css']);
            fclose($fp);

            Notices::message(__('Style sheet upgraded.'), true, true);
        }

        return true;
    }

    public static function render(): void
    {
        if (!self::status()) {
            return;
        }

        $css_content = is_file(dcCore::app()->admin->css_file) ? file_get_contents(dcCore::app()->admin->css_file) : '';

        echo
        '<p class="area"><label>' . __('Style sheet:') . '</label> ' .
        form::textarea('css', 60, 20, Html::escapeHTML($css_content)) . '</p>';
    }
}

Le contenu de ce document a été écrit suivant le code de la version 2.27 de Dotclear.

Fichier Frontend d'un module

Jean-Christian Denis — Sun, 16 Jul 2023 13:48:00 +0100

Le fichier Frontend.php, placé dans le dossier src du module, permet de préparer le nécessaire à son fonctionnement en partie public.

Le fichier Frontend.php fait partie du processus reconnu par le gestionnaire de modules, il est donc automatiquement pris en compte coté public si il existe.

Il est placé dans le sous dossier src du module,
Il contient une classe du nom de Frontend,
Il est dans l'espace de nom PHP Dotclear\Plugin\monPlugin ou Dotclear\Theme\monTheme,
La classe doit étendre la classe Process,
Seules les méthodes init() et process() sont utilisées,

Généralement cette classe est utilisée pour préparer des variables nécessaires au fonctionnement du module, déclarer ses templates, ajouter ses behaviors, pour la partie publique des blogs.

Exemple du fichier Frontend.php du plugin blogroll de la distribution :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\blogroll;

use dcCore;
use Dotclear\Core\Process;

class Frontend extends Process
{
    public static function init(): bool
    {
        return self::status(My::checkContext(My::FRONTEND));
    }

    public static function process(): bool
    {
        if (!self::status()) {
            return false;
        }

        dcCore::app()->tpl->addValue('Blogroll', [FrontendTemplate::class, 'blogroll']);
        dcCore::app()->tpl->addValue('BlogrollXbelLink', [FrontendTemplate::class, 'blogrollXbelLink']);

        dcCore::app()->addBehaviors([
            'initWidgets'        => [Widgets::class, 'initWidgets'],
            'initDefaultWidgets' => [Widgets::class, 'initDefaultWidgets'],
        ]);

        return true;
    }
}

Le contenu de ce document a été écrit suivant le code de la version 2.27 de Dotclear.

Fichier Backend d'un module

Jean-Christian Denis — Sun, 16 Jul 2023 13:36:00 +0100

Le fichier Backend.php, placé dans le dossier src du module, permet de préparer le nécessaire à son fonctionnement pour sa partie administration.

Le fichier Backend.php fait partie du processus reconnu par le gestionnaire de modules, il est donc automatiquement pris en compte dans l'administration si il existe.

Il est placé dans le sous dossier src du module,
Il contient une classe du nom de Backend,
Il est dans l'espace de nom PHP Dotclear\Plugin\monPlugin ou Dotclear\Theme\monTheme,
La classe doit étendre la classe Process,
Seules les méthodes init() et process() sont utilisées,

Généralement cette classe est utilisée pour préparer des variables nécessaires au fonctionnement du module, ajouter ses menus, favoris, behaviors, pour la partie administration des blogs.

Exemple du fichier Backend.php du plugin aboutConfig de la distribution :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\aboutConfig;

use Dotclear\Core\Backend\Menus;
use Dotclear\Core\Process;

class Backend extends Process
{
    public static function init(): bool
    {
        return self::status(My::checkContext(My::BACKEND));
    }

    public static function process(): bool
    {
        if (self::status()) {
            My::addBackendMenuItem(Menus::MENU_SYSTEM);
        }

        return self::status();
    }
}

Le contenu de ce document a été écrit suivant le code de la version 2.27 de Dotclear.

Fichier Prepend d'un module

Jean-Christian Denis — Sun, 16 Jul 2023 10:38:00 +0100

Le fichier Prepend.php, placé dans le dossier src du module, permet de préparer le nécessaire à son fonctionnement.

Le fichier Prepend.php fait partie du processus reconnu par le gestionnaire de modules, il est donc automatiquement pris en compte si il existe.

Il est placé dans le sous dossier src du module,
Il contient une classe du nom de Prepend,
Il est dans l'espace de nom PHP Dotclear\Plugin\monPlugin ou Dotclear\Theme\monTheme,,
La classe doit étendre la classe Process,
Seuls les méthodes init() et process() sont utilisées,

Généralement cette classe est utilisée pour préparer des variables nécessaires au fonctionnement global du module ou pour ajouter des behaviors, à la fois coté admin et coté public. Si ces définitions sont propres à l'admin ou au public, il faut utiliser les fichiers Backend.php ou Frontend.php.

Exemple du fichier Prepend.php du plugin blogroll de la distribution :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\blogroll;

use dcCore;
use Dotclear\Core\Process;

class Prepend extends Process
{
    public static function init(): bool
    {
        return self::status(My::checkContext(My::PREPEND));
    }

    public static function process(): bool
    {
        if (!self::status()) {
            return false;
        }

        dcCore::app()->url->register('xbel', 'xbel', '^xbel(?:\/?)$', [FrontendUrl::class, 'xbel']);

        return true;
    }
}

Le contenu de ce document a été écrit suivant le code de la version 2.27 de Dotclear.

Structure d'un module

Jean-Christian Denis — Tue, 11 Jul 2023 21:09:00 +0100

Avec la version 2.27 de Dotclear la structure de plugins et thèmes devient plus rigide. Cette structure deviendra obligatoire assez rapidement.

La structure générale d'un module est quasi commune aux plugins et aux thèmes. Elle se définit comme suit.

Nom

Depuis la mise en place des espaces de nom pour les modules, le nom du répertoire racine du module sera son ID et son espace de nom PHP. De ce fait il est proscrit tous caractères autres que des chiffres et lettres et le nom doit commencer par une lettre.

Invalide : mon-plugin, 1to3plugin,
Valide : monplugin, MonPlugin2,

Fichiers à la racine du module :

_define.php : Fichier de définition
_disabled : Fichier de désactivation
_init.php : Fichier de définition d'initialisation
CHANGELOG.md : récapitulatif des modifications/versions
dcstore.xml : Fichier de définition de dépôt distant
icon.svg : Icône
icon-dark.svg : Icône sombre
LICENSE : Licence
README.md : Document d'introduction

Répertoires à la racine du module :

css : Feuilles de styles
default-templates : Templates
img : Images
js : Scripts javascript
locales : Traductions
src : Espace de nom contenant tous les fichiers .php

Fichiers du dossier src :

Backend.php : ex _admin.php Préparation de la partie admin,
Config.php : ex _config.php Configurateur,
Frontend.php : ex _public.php Préparation de la partie publique
Install.php : ex _install.php Processus d'installation
Manage.php : ex index.php Page de gestion principale
My.php : fonctions prédéfinies d'aides au code
Prepend.php : ex _prepend.php Préparation générale
Widgets.php : ex _widgets.php Gestion des widgets par le plugin widgets

Bonnes pratiques

Il est vivement recommandé (possible obligation à l'avenir) d'utiliser l'ID du module pour l'identifiant de ses paramètres dans les espaces de paramètres (blog settings) et les espaces de préférences (user pref).
Il est recommandé de séparer les behaviors trop volumineux des fichiers Backend.php / Frontend.php et de les mettre dans un fichier BackendBehaviors.php / FrontendBehaviors.php.
De manière générale le nom de fichier et donc de classe doit être en rapport avec sa fonction, par exemple une classe contenant toutes les méthodes en rapport aux templates coté public sera nommé FrontendTemplate.

Ce document est en cours d'écriture, il est incomplet.

Le contenu de ce document a été écrit suivant le code de la version 2.27 de Dotclear.