Squelette du plugin

Ce qui suit est le standard pour la structure d’un plugin dans Elgg à partir de Elgg 2.0.

Exemple de structure

Voici un exemple de plugin avec un structure standard. Pour plus d’explications sur cette structure, voyez les informations dans les sections suivantes. Votre plugin peut ne pas avoir besoin de tous les fichiers listés

Les fichiers suivants pour le plugin example iraient dans /mod/example/

actions/
    example/
        action.php
        other_action.php
classes/
    VendorNamespace/
        PluginNamespace/
            ExampleClass.php
languages/
    en.php
vendors/
    example_3rd_party_lib/
views/
    default/
        example/
          component.css
          component.js
          component.png
        forms/
            example/
                action.php
                other_action.php
        object/
            example.php
            example/
                context1.php
                context2.php
        plugins/
            example/
                settings.php
                usersettings.php
        resources/
            example/
                all.css
                all.js
                all.php
                owner.css
                owner.js
                owner.php
        widgets/
            example_widget/
                content.php
                edit.php
elgg-plugin.php
CHANGES.txt
COPYRIGHT.txt
INSTALL.txt
LICENSE.txt
README.txt
composer.json

Fichiers requis

Les plugins doivent fournir un fichier composer.json dans la racine du plugin afin d’être reconnus par Elgg.

De ce fait, voici la structure conforme minimale :

mod/example/
    composer.json

Actions

Les plugins devraient placer les scripts pour les actions dans un dossier actions/, et devraient en outre utiliser le nom de l’action pour déterminer l’emplacement dans ce dossier.

Par exemple, l’action my/example/action irait dans my_plugin/actions/my/example/action.php. Ceci permet de rendre évident quel script est associé avec quelle action.

De même, le corps du formulaire qui est soumis à cette action doit être situé dans forms/my/example/action.php. Non seulement cela rend évident le lien entre le gestionnaire d’action, le code du formulaire, et le nom de l’action, mais cela vous permet aussi d’utiliser facilement la fonction elgg_view_form().

Fichiers texte

Les plugins peuvent fournir divers fichiers *.txt comme documentation supplémentaire pour le plugin. Ces fichiers doivent utiliser la syntaxe Markdown et vont générer des liens vers les sections de gestion du plugins.

README.txt

devrait fournir des informations supplémentaires de toute nature sur le plugin

COPYRIGHT.txt

Si inclus, doit fournir une description du droit d’auteur du plugin.

LICENSE.txt

Si inclus, doit fournir le texte de la licence sous laquelle le plugin est publié.

INSTALL.txt

Si inclus, doit fournir des instructions supplémentaires pour l’installation du plugin si le processus est suffisamment compliqué (par exemple, s’il nécessite l’installation de bibliothèques tierces sur l’hôte, ou nécessite l’acquisition d’une clef API provenant d’un tiers).

CHANGES.txt

Si inclus, doit fournir une liste de modifications pour le plugin, regroupées par numéro de version, avec la version la plus récente au début.

Les plugins peuvent inclure des fichiers supplémentaires *.txt en plus de ceux-ci, mais aucune interface n’est fournie pour les lire.

Pages

Pour afficher des pages complètes, les plugins doivent utiliser les vues de ressources (qui ont des noms commençant par resources/). Cela permet à d’autres plugins de remplacer facilement certaines fonctionnalités via le système de vue.

Note

La raison pour laquelle nous encourageons cette structure est

• Pour former une relation logique entre URLs et scripts, de sorte que les personnes qui examinent le code puissent avoir une idée de ce qu’il fait rien qu’en examinant la structure du code.

• Pour nettoyer le répertoire racine des plugins, qui avait historiquement été rapidement encombré avec les scripts de gestion des pages.

Classes

Elgg fournit un autochargement PSR-0 de toutes les classes du répertoire classes/ des plugins actifs.

Vous êtes encouragés à suivre les standards PHP-FIG quand vous écrivez vos classes.

Note

Les fichiers avec une extension « .class.php » ne seront pas reconnus par Elgg.

Lors de l’organisation de vos classes, Elgg n’impose pas une structure spécifique. Utilisez ce qui fonctionne le mieux pour votre plugin, mais gardez à l’esprit qu’il devrait être facile à lire, et que ses fonctionnalités devraient être faciles à trouver, et qu’avoir des fonctions séparées dans différentes classes permettra d’améliorer la maintenabilité et la testabilité.

Fournisseurs - vendors

Les bibliothèques tierce-partie de tout type devraient être placées dans le dossier vendors/ de la racine du plugin. Quoique ce dossier n’ait pas de signification particulière pour le moteur de Elgg, il a été historiquement l’emplacement où le noyau de Elgg conservait ses bibliothèques tierces-parties, aussi nous encourageons le même format au nom de la cohérence et de la familiarité.

Vues

Afin de surcharger des vues du noyau, les vues d’un plugin peuvent être placées dans views/, ou un fichier de configuration elgg-plugin.php peut être utilisé pour un mappage fichier/chemin plus détaillé. Voyez Vues.

Javascript et CSS seront hébergés dans le système de vues. Voyez JavaScript.