DotclearWatch / Blog - Mot-clé - theme

[2.36] Mode dévelopement pour l'éditeur de thème

Jean-Christian Denis — Tue, 19 Aug 2025 11:34:00 +0200

Dotclear 2.35 introduisait une nouvelle gestion de surcharge de thèmes, et dans le version 2.36 une option de mode de dévelopement fait son appartition dans l'éditeur de thème.

Le nouveau behavior themeEditorDevMode, si il retourne vrai, permet de modifier sur place les fichiers d'un thème dans l'éditeur de thème.

Il suffit de l'activer en appelant le beharvior comme suit :

App::behavior()->addBehavior('themeEditorDevMode', fn(): bool => true);

Un message apparaitra lors de la modification d'un thème.

Le plugin tidyAdmin dans sa version pour Dotclear 2.36 propose une option pour faire cela depuis l'interface utilisateur.

Le plugin Uninstaller

Jean-Christian Denis — Tue, 22 Aug 2023 12:00:00 +0200

La prochaine version 2.28 de Dotclear embarque un nouveau plugin nommé Uninstaller.

But

Le gestionnaire de modules, incorporé au core de Dotclear et servant à la gestion des thèmes et plugins, permet d'installer des modules avec une gestion des actions liées à l'installation à travers le fichier src/Install.php et sa classe idoine, mais lorsqu'il s'agit de désinstaller des plugins ou thèmes, la seule action effectuée est la suppression des fichiers du module. À aucun moment on ne tient compte de ce que le module a pu ajouter dans les paramètres, les tables, le cache, etc...

Ce manque est désormais comblé par le plugin Uninstaller qui va permettre d'affiner la désinstallation d'un module, en proposant des outils préétablis de suppressions. Il y a deux points de départ de ces désinstallations, soit depuis le gestionnaire de plugins|thèmes avec un bouton Désinstallation qui donnera le choix au super admin de supprimer telle ou telle partie du module, soit directement lors de l'action de suppression d'un module auquel cas des actions définies par le module lui-même seront effectuées directement sans demande de confirmation.

Interface utilisateur du plugin Uninstaller

Actions

Une tâche (Cleaner) permet d'effectuer une action ciblée, les groupes et tâches prédéfinis sont les suivants :
Caches :

caches.delete : Effacer le répertoire de caches créé par le module,
caches.empty : Vider le répertoire de caches créé par le module,

Logs :

logs.delete_all : Effacer les logs créés par le module,

Plugins :

plugins.delete : Effacer les fichiers du plugins,

Preferences :

preferences.delete_global : Effacer les préférences pour les utilisateurs créées par le module,
preferences.delete_local : Effacer les préférences globales créées par le module,
preferences.delete_all : Effacer les préférences globales et utilisateurs créées par le module,
preferences.delete_related : Effacer une préférence ciblée créé par le module,

Settings :

settings.delete_global : Effacer les préférences pour les blogs créées par le module,
settings.delete_local : Effacer les préférences globales créées par le module,
settings.delete_all : Effacer les préférences globales et blogs créées par le module,
settings.delete_related : Effacer une préférence ciblée créé par le module,

Tables :

tables.delete : Supprimer une table créée par le module,
tables.empty : Vider une table créée par le module,

Themes :

themes.delete : Effacer les fichiers du thème,

Vars :

vars.delete : Effacer ou vider le sous répertoire de DC_VAR créé par le module,

Versions :

versions.delete : Supprimer le numéro de version du module ne base

Intégration

Pour utiliser les fonctions de désinstallation prédéfinis, il suffit d'ajouter un fichier src\Uninstall.php contenant sa classe idoine Uninstall dans le module. Le plugin Uninstaller saura trouver et utiliser ce fichier sans déclaration supplémentaire.
La méthode addUserAction va ajouter une action avec demande de confirmation tandis que la méthode addDirectAction ajoutera une action directe lors de la suppression d'un module. Exemple complet de fichier :

<?php
declare(strict_types=1);

namespace Dotclear\Theme\monTheme;

use Dotclear\App;
use Dotclear\Core\Process;
use Dotclear\Plugin\Uninstaller\Uninstaller;

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

    public static function process(): bool
    {
        // Par sécurtié, on vérifie l'existence du plugin Uninstaller, même si c'est lui qui a dû appeler ce script
        if (!self::status() || !App::plugins()->moduleExists('Uninstaller')) {
            return false;
        }

        // On récupère l'instance singleton de Uninstaller
        Uninstaller::instance()
            // Action utilisateur pour effacer les paramètres aillant l'espace de nom du module
            ->addUserAction(
                'settings',
                'delete_all',
                My::id()
            )
            // Action utilisateur pour effacer les fichiers du module
            ->addUserAction(
                'plugins',
                'delete',
                My::id()
            )
            // Action utilisateur pour effacer le numéro de version en base du module
            ->addUserAction(
                'versions',
                'delete',
                My::id()
            )
            // Action directe pour effacer les fichiers du module
            ->addDirectAction(
                'plugins',
                'delete',
                My::id()
            )
            // Action directe pour effacer le numéro de version en base du module
            ->addDirectAction(
                'versions',
                'delete',
                My::id()
            )
        ;

        // aucune action spécifique, on retourne donc false
        return false;
    }
}

Extensions

Il est possible d'aller plus loin en ajoutant des actions spécifiques qui n'existent pas dans la livraison du plugin Uninstaller.
Pour des actions avec confirmation utilisateur on va simplement compléter la classe précédente comme suit :

<?php
declare(strict_types=1);

namespace Dotclear\Theme\monTheme;

use Dotclear\App;
use Dotclear\Core\Process;
use Dotclear\Helper\Html\Form\Para;
use Dotclear\Helper\Html\Form\Checkbox;
use Dotclear\Helper\Html\Form\Label;
use Dotclear\Plugin\Uninstaller\Uninstaller;

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

    public static function process(): bool
    {
        // Par sécurtié, on vérifie l'existence du plugin Uninstaller, même si c'est lui qui a dû appeler ce script
        if (!self::status() || !App::plugins()->moduleExists('Uninstaller')) {
            return false;
        }

        // ... ici les actions prédéfinies utilisateur et directes ne sont pas affichées cf exemple ci-dessus

        if (!empty($_POST['mon_action_perso']) {

            // Ici on exécute la tâche de supprimer la choucroute

        }

        // on retourne true pour indiquer qu'on a un formulaire
        return true;
    }

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

        // On affiche le formulaire spécial
        echo (new Para())
            ->items([
                (new Checkbox('mon_action_perso', true))
                    ->value(1),
                (new Label('supprimer la choucroute', Label::OUTSIDE_LABEL_AFTER))
                    ->for('mon_action_perso')
                    ->class('classic'),
            ])
            ->render(); 
    }
}

Il est possible d'aller encore plus loin pour créer des actions spécifiques plus poussées, il faut alors créer un Cleaner et le déclarer de la même manière que ceux du plugin Uninstaller. Voir les fichiers Prepend.php pour la déclaration d'un Cleaner et le répertoire /src/Task pour des exemples de tâches.

NOTE

Pour des raisons techniques les actions directes ne sont pas effectuées sur les modules installés en double, et ce même si le bouton Désinstaller est présent.

Les informations distillées ici sont non exhaustives et pourront être complétées à l'avenir, elles ont été écrites d'après la version 2.28 de Dotclear.

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.

Fichier de dépôt tiers

Jean-Christian Denis — Fri, 14 Jul 2023 20:25:00 +0100

Depuis quelques versions le gestionnaire de modules de Dotclear supporte les dépôts tiers. Le fichier dcstore.xml se trouvant à la racine du module permet de définir ce dépôt.

En réalité l'emplacement de ce fichier n'est pas dans le module mais là où est hébergé le dépôt tiers ! Par commodité et comme souvent le dépôt tiers est un dépôt github en le plaçant dans le module, le développeur garantit qu'il sera présent sur son dépôt.
L'emplacement final de ce fichier est renseigné dans le fichier de définition du module dans le paramètre 'repository'.
Son contenu est écrit en xml et est calqué sur le dépôt officiel Dotaddict.org. Voici l'exemple du plugin tweakStore :

<?xml version="1.0"?>
<modules xmlns:da="http://dotaddict.org/da/">
  <module id="tweakStores">
    <name>Tweak stores</name>
    <version>0.8</version>
    <author>Jean-Christian Denis and Contributors</author>
    <desc>Helper to manage external repositories</desc>
    <file>https://github.com/JcDenis/tweakStores/releases/download/v0.8/plugin-tweakStores.zip</file>
    <da:dcmin>2.26</da:dcmin>
    <da:details>https://plugins.dotaddict.org/dc2/details/tweakStores</da:details>
    <da:support>https://github.com/JcDenis/tweakStores</da:support>
  </module>
</modules>

Pas besoin d'explication sur son contenu, il reprend en grande partie les informations présentes dans define.php du module en ajoutant le lien vers le fichier Zip du module.
N.D.L.R : En théorie un fichier de dépôt tiers pourrait contenir les informations de plusieurs modules, en pratique, je n'ai pas testé.

Il existe des plugins qui permettent de créer automatiquement ce fichier et également des scripts. (Liens non exhaustifs à titre d'exemple.)

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

Fichier init d'un module

Jean-Christian Denis — Fri, 14 Jul 2023 19:54:00 +0100

Le fichier _init.php d'un module permet principalement d'initialiser des constantes sans même que le module soit chargé. Ce fichier se place à la racine du module.

Le rôle de ce fichier est de pouvoir charger des constantes avant même que le module soit chargé afin de partager avec d'autres modules certaines valeurs et ceci même si le module est désactivé.
Ce fonctionnement est spécial et ce fichier ne doit contenir que le minimum d'informations qui devront si possible ne pas changer à chaque version du module. (Sinon tout l'intérêt de ce fichier est perdu.)
Généralement la classe contenue dans ce fichier permet de définir des noms de permissions ou de tables.
Exemple tiré du plugin blogroll de la distribution :

<?php
// aucun espace de nom PHP n'est déclaré

// Cette classe sera accessible à tous les autres modules
class initBlogroll
{
    // On définit le nom de la permission liée à blogroll
    public const PERMISSION_BLOGROLL = 'blogroll';

    // On définit le nom de la table de base de données de blogroll
    public const LINK_TABLE_NAME = 'link';
}

Il est recommandé de garder des noms de classe et de constantes dans le style de l'exemple ci-dessus.
Cette classe va permettre par exemple au plugin blogroll lui même de définir ses permissions dans son fichier de définition :

<?php
 
$this->registerModule(
    // ...
    [
        'permissions' => dcCore::app()->auth->makePermissions([
            initBlogroll::PERMISSION_BLOGROLL,
        ]),
        'type'        => 'plugin',
    ]
);

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

Les classes de module My

Jean-Christian Denis — Fri, 14 Jul 2023 10:27:00 +0100

Dotclear version 2.27 propose pour les plugins et thèmes des classes d'aide pour simplifier l'écriture du code.

Deux classes My (qui étendent une troisième commune nommé MyModule) sont disponibles, MyPlugin pour les plugins et MyTheme pour les thèmes, elle fournissent des méthodes statiques qui vont simplifier l'écriture des modules.

Inclusion

Pour les utiliser il suffit d'inclure dans le dossier src du module un fichier My.php avec le contenu suivant :

<?php
/**
 * Mettre ici les informations de licence.
 */
declare(strict_types=1);

namespace Dotclear\Plugin\monPlugin;

use Dotclear\Module\MyPlugin;

class My extends MyPlugin
{
}

A adapter pour un thème. Il possible d'ajouter ses propres méthodes à cette classe tant que ça n'interfère pas avec celles de MyPlugin, MyTheme et MyModule.

Utilisation

Ensuite il sera possible d'utiliser toutes les méthodes de MyPlugin (MyTheme) dans les classes du plugin (thème).

<?php
namespace Dotclear\Plugin\monPlugin;

use Dotclear\Core\Process;
use Dotclear\Core\Backend\Page;

// Page principale de gestion du plugin
class Manage extends Process
{
    public static function init(): bool
    {
        // On vérifie que l'utilisateur à le droit d'exercer dans ce contexte
        return self::status(My::checkContext(My::MANAGE));
    }

    public static function process(): bool
    {
        if (!empty($_POST['step'])) {
            // ...

            // On redirige la page à l'aide de My
            My::redirect(['step' => 2]);
        }
    }

    public static function render(): void
    {
        // On utilise la classe My pour trouver le nom du plugin et des fichiers
        Page::openModule(
            My::name(),
            My::cssLoad('backend')
        );
    }
}

Méthodes

My::define()

protected static function define(): dcModuleDefine

Cette méthode renvoie l'instance de définition du module.

My::checkContext()

protected static function checkContext(int $context): bool

Cette méthode permet de vérifier que l'utilisateur à le droit d'exercer dans un certain contexte, elle renvoie true si l'utilisateur à assez de droits, false sinon. Elle prend en paramètre le contexte qui doit être vérifier. La liste des contextes prédéfinis est disponible dans les constantes de la classe My :

0 : INSTALL : Install context
1 : PREPEND : Prepend context
2 : FRONTEND : Frontend context
3 : BACKEND : Backend context (usually when the connected user may access at least one functionnality of this module)
4 : MANAGE : Manage context (main page of module)
5 : CONFIG : Config context (config page of module)
6 : MENU : Menu context (adding a admin menu item)
7 : WIDGETS : Widgets context (managing blog's widgets)
8 : UNINSTALL : Uninstall context (réservé pour le plugin Uninstaller)

My::checkCustomContext()

protected static function checkCustomContext(int $context): ?bool

Cette méthode est appelée en début de la méthode précédente checkContext et peut être réécrite dans la classe My du module si on en a besoin. Elle permet d'utiliser ses propres droits, ou de modifier des droits de contexte de la méthode précédente. Si checkCustomContext() renvoie null alors les contextes de la classe précédente seront testés.
Exemple avec le fichiers My du plugin userPrefs de la distribution :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\userPref;

use dcCore;
use Dotclear\Module\MyPlugin;

class My extends MyPlugin
{
    protected static function checkCustomContext(int $context): ?bool
    {
        // allways limit to super admin
        return defined('DC_CONTEXT_ADMIN')
            && dcCore::app()->auth->isSuperAdmin();
    }
}

My::path()

public static function My::path(): string

Cette méthode renvoie le chemin du dossier du module.

My::id()

protected static function My::id(): string

Cette méthode renvoie l'identifiant du module.

My::name()

protected static function My::name(): string

Cette méthode renvoie le nom traduit du module.

My::settings()

public static function settings(): ?dcNamespace

Cette méthode renvoie l'instance de l'espace de paramètres du module. Le module doit utiliser son ID comme nom d'espace de paramètre pour pouvoir utiliser cette méthode.

My::prefs()

public static function prefs(): ?dcWorkspace

Cette méthode renvoie l'instance de l'espace de préférences du module. Le module doit utiliser son ID comme nom d'espace de préférences pour pouvoir utiliser cette méthode.

My::l10n()

public static function l10n(string $process): void

Cette méthode charge les locales du module pour un process donné (main, public, plugin, etc...).

My::fileURL()

public static function fileURL(string $resource, bool $frontend = false): string

Cette méthode retourne l'URL d'un fichier de module. Cette méthode tient compte du contexte courant (admin, public). Pour forcer le retour de l'URL public dans le contexte admin, il suffit de mettre le paramètre $frontend à true.
A noter que pour les thèmes, cette méthode renvoie toujours l'URL publique.

My::cssLoad()

public static function cssLoad(string $resource, string $media = 'screen', ?string $version = ''): string

Cette méthode retourne le code HTML pour inclure un fichier CSS $resource du module.

Si le paramètre $resource ne commence pas par un / le fichier sera cherché dans le sous dossier css du module,
Si l'extension du fichier n'est pas incluse à $resource, elle sera ajoutée,
Le type de $media peut-être précisé, par défaut ce sera screen,
Un numéro de version peut-être ajouté à la fin de l'url de ressource (gestion de cache)

// Renvoie le code pour le fichier .../monPlugin/css/frontend.css
My::cssload('frontend');
// Renvoie le code pour le fichier .../monPlugin/style.css
My::cssLoad('/style.css');

My::jsLoad()

public static function jsLoad(string $resource, ?string $version = '', bool $module = false): string

Tout comme My::cssLoad() cette méthode renvoie le code HTML pour ajouter un fichier JS du module. Le paramètre $module si il est à true permet de charger $resource comme un module JS.

My::addBackendMenuItem() (plugins uniquement)

public static function addBackendMenuItem(string $menu = Menus::MENU_PLUGINS, array $params = [], string $scheme = '(&.*)?$', ?string $id = null): void

Cette méthode permet d'ajouter rapidement le module aux menus de l'administration.
Le menu est à choisir parmi ceux définis dans les constantes de Dotclear\Core\Backend\Menus et par défaut celui des plugins :

Menus::MENU_BLOG => 'Blog',
Menus::MENU_SYSTEM => 'System',
Menus::MENU_PLUGINS => 'Plugins',

Les paramètres :

$params sert à ajouter des paramètres à l'URL du menu,
$scheme permet de personnaliser la surbrillance du menu,
$id permet de spécifier un id pour l’icône de tableau de bord (Utile aux behaviors).

My::icons() (plugins uniquement)

public static function icons(string $suffix = ''): array

Cette méthode renvoie un tableau des chemins complets vers les icônes du modules.

My::manageURL() (plugins uniquement)

public static function manageUrl(array $params = [], string $separator = '&'): string

Cette méthode renvoie l'URL de la page principale de gestion du module. Des paramètres spéciaux peuvent être ajoutés avec $params, et le séparateur des paramètres peut être modifié avec le paramètre $separator.

My::redirect() (plugins uniquement)

public static function redirect(array $params = [], string $suffix = ''): void

Cette méthode effectue une redirection en prenant l'URL de base du module, à laquelle il est possible d'ajouter des paramètres $params. Le paramètre $suffix permet d'ajouter par exemple le renvoi vers un onglet spécifique.

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

Fichier de désactivation d'un module

Jean-Christian Denis — Fri, 14 Jul 2023 00:39:00 +0100

Le fichier de désactivation en dur d'un module se nomme _disabled, c'est un fichier vide qui est placé à la racine du module.

Normalement ce fichier n'est pas à manipuler, le gestionnaire de modules se charge de l'ajouter suivant des prérequis ou des actions définies.
Le gestionnaire de module va lire le fichier de définition du module et si les prérequis du module ne sont pas remplis, il désactivera le module en ajoutant le fichier _disabled à sa racine.
Depuis l'interface d'administration du blog, dans la liste des plugins ou des thèmes installés, il est possible de désactiver ou de réactiver des modules.
Une fois ce fichier présent, seul le fichier de définition du module est lu.

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

Fichier de définition d'un module

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

Le fichier de définition se situe à la racine du module, il se nomme _define.php et il va donner à Dotclear toutes les informations indispensables à sa compréhension. Il est en très grande partie commun aux thèmes et aux plugins.

Son contenu peut être le suivant :

<?php
/**
 * Mettre ici les informations de licence
 */
$this->registerModule(
    'Le module', // Nom (requis)
    'Un module qui ne fait rien', // Description (requis)
    'Jean-Christian Denis and contributors', // Auteur (requis)
    '1.0',  // Version (requis)
    [
        'requires' => [
            ['php', '8.1'], // Version minimum de PHP (optionnel)
            ['core', '2.26'], // Version miminum de Dotclear (recommandé)
            ['UnAutreModule', '1.1'], // Dépendance à un autre module (optionnel)
        ],
        'priority' => 1000, // priorité, nombre entier positif (optionnel)
        'permissions' => dcCore::app()->auth->makePermissions([
            dcCore::app()->auth::PERMISSION_CONTENT_ADMIN,
        ]), // Permissions (recommandé)
        'type' => 'plugin', // type de module, plugin ou theme (requis)
        'settings'    => [
            'blog' => '#params.LeModule', // plugin, sa configuration est sur la page de paramètres du blog
            'self' => '', // plugin, sa page de gestion est sa page de configuration
            'pref' => '#user-options.LeModule', // plugin, sa configuration est dans les préférences utilisateur
        ],
        'parent' => 'ductile', // thème, son parent (optionnel)
        'tplset' => 'mustek', // thème, le jeu de template à utiliser (optionnel)
        'standalone_config' => true, // thème, utilisation de sa propre configuration (optionnel)
        'support' => 'https://github.com/JcDenis/LeModule', // Lien vers la page du support (recommandé)
        'details' => 'https://plugins.dotaddict.org/dc2/details/LeModule', // Lien vers la page de détails (recommandé)
        'repository' => 'https://raw.githubusercontent.com/JcDenis/LeModule/master/dcstore.xml', // Lien vers la définition du dépôt tiers (optionnel)
        'widgettitleformat'     => '', // formatage de widget (optionnel)
        'widgetsubtitleformat'  => '', // formatage de widget (optionnel)
        'widgetcontainerformat' => '', // formatage de widget (optionnel)
    ]
);

Attention : Ce fichier est appelé très tôt dans le code, à l'intérieur d'une méthode, il peut être appelé plusieurs fois et d'autres script peuvent l'appeler, à cause de tout cela seules les classes dcAuth, dcCore et celles contenues dans les fichiers _init.php des modules peuvent être utilisées dans ce fichier.

A noter : Si la page de configuration du plugin est dans un fichier src/Config.php, Dotclear l'indiquera de manière automatique, il n'est pas nécessaire de l'indiquer dans la définition des paramètres settings.

La présence du fichier define.php est obligatoire.

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.

La class Process

Jean-Christian Denis — Tue, 11 Jul 2023 20:41:00 +0100

La classe Process introduite dans les dernières versions de Dotclear devient la norme et est requise quasi partout depuis Dotclear 2.27.

La plupart des classes de plugins et thèmes doivent étendre la classe Process, pour cela il suffit de déclarer son utilisation en début de fichier puis d'étendre votre classe.

<?php
use Dotclear\Core\Process;

class Manage extends Process
{
}

Cette classe est pour l'instant très succincte mais permet de découper le déroulement du script en trois parties.

Première partie

Elle utilise la méthode Process::init() elle permet de vérifier les droits à utiliser votre classe. Elle utilise un mécanisme mémorisant le statut de cette initialisation, verrouillant ou non l'utilisation des méthodes suivantes.

public static function init(): bool
{
    // On enregistre la permissions d'utiliser la classe et on renvoie le résultat
    return self::status(My::checkContext(My::MANAGE));
}

On voit ici l'utilisation de la classe My qui est un outil d'aide à l'écriture des modules simplifiant l'utilisation de certains mécanismes.

Seconde partie

Elle utilise la méthode Process::process() qui est consacrée à la préparation et au traitement des données, telles que celles des formulaires par exemple.

public static function process(): bool
{
    // On vérifie le droit d'effectuer cette partie
    if (!self::status()) {
        return false;
    }

    if (!empty($_POST['id'])) {
        // traitement de mon formulaire

        // On a réussi, on ajoute un message
        Notices::addSuccessNotice(__('Victory'));
        // On redirige vers la page du plugin
        dcCore::->admin->url->redirect('admin.plugin.' . My::id());
    }

    // Cette méthode doit retourner true si on veut exécuter la troisième partie
    return true;
}

La troisième partie

Elle utilise la méthode Process::render() qui est consacré au rendu. C'est à dire à l'affichage dans le navigateur.

public static function render(): void
{
    // On vérifie le droit d'effectuer cette partie
    if (!self::status()) {
        return;
    }

    // On prépare l'affichage du haut de page
    Page::openModule(My::name());

    // On ajoute le menu façon Dotclear
    echo
    Page::breadcrumb(
        [
            __('Plugin')  => '',
            My::name() => '',
        ]
    ) .
    // On affiche d'éventuelle messages
    Notices::getNotices();

    // On ajoute le contenu de la page
    echo __('yeah!');

    // On ajoute l'aide de la page
    Page::helpBlock(My::id());

    // On ferme la page
    Page::closeModule();
}

Ici on voit l'utilisation des classes d'outils My et Page qui vont grandement faciliter l'écriture des plugins et thèmes.

A noter que seule la première méthode init() est obligatoire. Si elle renvoie true, c'est que la classe ne contient pas de méthode process(), la méthode render() sera exécuté.

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