Les classes de module My

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.