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/
        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
activate.php
deactivate.php
elgg-plugin.php
CHANGES.txt
COPYRIGHT.txt
INSTALL.txt
LICENSE.txt
manifest.xml
README.txt
start.php

Fichiers requis

Les plugins doivent fournir un fichier start.php et manifest.xml dans la racine du plugin afin d’être reconnus par Elgg.

De ce fait, voici la structure conforme minimale :

mod/example/
    start.php
    manifest.xml

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 renvoie vers cette action doit être situé dans forms/mon/exemple/action.php. Non seulement cela rend évident la connexion entre le gestionnaire d’action, le code de formulaire et le nom de l’action, mais il vous permet d’utiliser la nouvelle (à partir de Elgg 1.8) fonction elgg_view_form() facilement.

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, en plus de ce qui est inclus dans manifest.xml

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 leur 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 donnée 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.

Fournisseurs (vendors)

Les bibliothèques tierce-partie devraient être placées dans le dossier vendors/ de la racine du plugin. Quoi que ce dossier n’ait pas de signification particulière pour Elgg, il a été historiquement l’emplacement où le noyau d’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.

activate.php et deactivate.php

Les fichiers activate.php et deactivate.php contiennent du code procédural qui sera exécuté respectivement lors de l’activation ou de la désactivation du plugin. Utilisez ces fichiers pour effectuer des événements uniques tels qu’enregistrer une note d’information d’administration permanente, enregistrer des sous-types, ou effectuer des opérations de nettoyage lorsque le plugin est désactivé.