Overview
Comment:Doc sur les plugins
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 27d16b542bd825230eef8c78fc3042d46af32346
User & Date: bohwaz on 2014-03-21 05:21:23
Other Links: manifest | tags
Context
2014-03-22
01:30
Mettre les champs vides à NULL avant de créer l'index sinon ça risque de foirer (deux champs vides ne sont pas uniques) check-in: 0e386a3a61 user: bohwaz tags: trunk
2014-03-21
05:21
Doc sur les plugins check-in: 27d16b542b user: bohwaz tags: trunk
04:18
Utile pour faire dépendre des plugins d'autres plugins : possibilité de récup la version installée d'un plugin check-in: d3c006672a user: bohwaz tags: trunk
Changes

Added doc/dev/plugins.skriv version [fadf7c1a26].

            1  += Les plugins dans Garradin =
            2  +
            3  +Garradin permet d'étendre ses fonctionnalités avec des plugins (appelés extensions dans la partie privée/admin de Garradin).
            4  +
            5  +L'interface de Garradin est séparée en deux sections : la section publique correspond au site web de l'association, accessible à tout visiteur, et la section privée, aussi appelée administration de l'association. Les plugins peuvent étendre l'une ou l'autre partie, ou même les deux.
            6  +
            7  +Les plugins peuvent être installés de deux manières :
            8  +# par le catalogue des extensions (extensions officielles)
            9  +# simplement en copiant le fichier de l'extension dans le répertoire "plugins/" de Garradin (extensions non-officielles)
           10  +
           11  +
           12  +== Bonnes pratiques ==
           13  +
           14  +Les plugins officiels sont relus et vérifiés avant publication et garantissent qu'ils ne devraient pas atteindre au bon fonctionnement de Garradin ou des autres plugins.
           15  +
           16  +Pour pouvoir être intégré au catalogue des plugins officiels il faut qu'il respecte un ensemble de règles édicté plus bas : [[règles du catalogue|#Règles du catalogue]].
           17  +
           18  +Les plugins non-officiels ne sont soumis à aucune règle mais il est quand même recommandé de suivre celles qui sont indiquées ici.
           19  +
           20  +=== Règles du catalogue ===
           21  +
           22  +Pour intégrer le catalogue des plugins officiels disponibles directement depuis Garradin le plugin doit :
           23  +
           24  +* être sous licence libre (compatible Debian et FOSS : GPL, AGPL, BSD, etc.) afin de pouvoir être maintenu dans le temps par la communauté ;
           25  +* avoir un code lisible et clair (peu importe la convention de codage) ;
           26  +* ne pas porter atteinte à l'intégrité et la stabilité de Garradin, cela implique :
           27  +** NE PAS patcher, éditer, supprimer ou ajouter de fichiers au code de Garradin lui-même : le plugin doit être contenu dans son archive. Il est par contre possible de faire dépendre un plugin de code ou composants contenus dans un autre plugin.
           28  +** NE PAS stocker de données en dehors de la base de données de Garradin.
           29  +** NE PAS ajouter, modifier ou supprimer directement des données dans la base de données de Garradin (hormis dans sa propre table).
           30  +** NE PAS enregistrer de documents sans utiliser les méthodes fournies par Garradin.
           31  +* respecter la vie privée des utilisateurs et notamment :
           32  +** NE PAS contacter un serveur distant (sauf besoin spécifique) ni transmettre des informations ou statistiques à un serveur tiers.
           33  +
           34  +== Détails techniques ==
           35  +
           36  +=== Format des plugins ===
           37  +
           38  +Les plugins sont des archives PHAR : tous les fichiers du plugin (code PHP, CSS, templates, images, etc.) sont stockés dans l'archive et y restent.
           39  +
           40  +Il est possible de créer soi-même l'archive PHAR de cette manière :
           41  +
           42  +[[[php
           43  +// Répertoire contenant l'arborescence du plugin
           44  +$source_dir = '/home/bohwaz/dev/plugins/test';
           45  +
           46  +// Fichier PHAR à créer
           47  +$dest = '/home/bohwaz/dev/garradin/src/plugins/test.phar';
           48  +
           49  +$p = new Phar($dest);
           50  +
           51  +$p->buildFromDirectory($source_dir);
           52  +
           53  +$p->compress(Phar::GZ);
           54  +
           55  +@unlink($dest);
           56  +rename($dest . '.gz', $dest);
           57  +]]]
           58  +
           59  +Un script PHP (**make_plugin.php**) est fourni dans le répertoire **tools/** de la version de développement de Garradin afin de vérifier l'arborescence et de créer l'archive PHAR en ligne de commande. Son utilisation est très simple :
           60  +
           61  + $ php -d phar.readonly=0 ~/dev/plugins/test ~/garradin/src/plugins/test.phar
           62  +
           63  +=== Informations sur le plugin (garradin_plugin.ini) ===
           64  +
           65  +Chaque plugin doit au moins fournir à la racine de son archive un fichier nommé ''garradin_plugin.ini''. Ce fichier fournit le nom, la description et quelques détails sur le plugin :
           66  +
           67  + nom="Ma première extension Garradin"
           68  + description="Affiche un message trop cool"
           69  + auteur="Anne Onyme"
           70  + url="http://garradin.eu/"
           71  + version="1.0"
           72  + menu=1
           73  + config=1
           74  +
           75  +La directive ''nom'' indique le nom du plugin, qui sera utilisé dans les listes et menus. ''description'' fournit une description plus longue d'une phrase ou deux, ''auteur'' donne le nom de l'auteur du plugin, et ''url'' indique l'adresse du site web de l'auteur.
           76  +
           77  +''version'' est utilisée pour savoir quelle est la version du plugin fournie dans l'archive. Voir plus loin : [[Mise à jour|#Mise à jour]].
           78  +
           79  +''menu'' indique à Garradin s'il doit afficher une entrée dans le menu des extensions de la partie privée. Cette entrée sera visible par tous les membres qui peuvent se connecter, même si l'extension restreint ensuite son accès. L'entrée du menu appellera le fichier **www/admin/index.php** qui devra donc exister, à défaut l'installation de l'extension échouera.
           80  +
           81  +''config'' indique si l'extension possède une configuration modifiable par l'utilisateur. Si positionné à 1 (ou ''true'') alors la page de gestion des extensions proposera un lien pour configurer l'extension (appelant le fichier **www/admin/config.php**), et le fichier **config.json** sera importé comme configuration par défaut. Ces deux fichiers sont donc obligatoires si ''config'' est activé.
           82  +
           83  +Attention, si le fichier **garradin_plugin.ini** n'existe pas dans l'archive elle ne pourra pas être installée, n'étant pas considérée comme un plugin de Garradin.
           84  +
           85  +=== Configuration du plugin ===
           86  +
           87  +Si ''config'' est positionné à 1 ou true (ou même ''On'') dans garradin_plugin.ini la configuration au format JSON stockée dans **config.json** sera importée comme configuration par défaut du plugin.
           88  +
           89  +Attention les objets javascript sont transformés en tableaux à l'import, il n'est donc pas possible de stocker un objet dynamique dans la configuration.
           90  +
           91  +=== Scripts magiques ===
           92  +
           93  +Chaque archive peut comporter certains ''scripts magiques'' qui seront appelés automatiquement par Garradin lors de certains événements.
           94  +
           95  +* **install.php** est appelé quand le plugin a été téléchargé et qu'il est déjà noté comme installé (post-installation), utile notamment pour créer une table dans la base de données
           96  +* **upgrade.php** : quand la version de l'archive (notée dans garradin_plugin.ini) ne correspond pas à la version enregistrée en base de donnée
           97  +* **uninstall.php** : juste avant que le plugin ne soit supprimé, utile par exemple pour supprimer une table créée dans la base de données
           98  +
           99  +Ces scripts ne peuvent pas être appelés par une requête HTTP via l'interface privée ou publique.
          100  +
          101  +=== Objet Garradin\Plugin ==
          102  +
          103  +* __construct(string $id)
          104  +* setConfig(string $key, string $value) : enregistre la configuration du plugin, si $value est null alors tte clé est effacée de la configuration
          105  +* getConfig(string $key) : récupère la valeur de la clé $key pour la configuration du plugin
          106  +* getInfos() : renvoie les informations enregistrées sur le plugin
          107  +* upgrade() : mise à jour du plugin
          108  +* needsUpgrade() : le plugin doit-il être mis à jour ?
          109  +* uninstall() : désinstaller le plugin
          110  +* id() : renvoie l'identifiant du plugin
          111  +* path() : renvoie le chemin vers l'archive PHAR du plugin
          112  +
          113  +=== Base de données ===
          114  +
          115  +Tous les plugins ont un accès illimité à la base de données principale de Garradin. Cependant il est interdit d'ajouter, modifier ou supprimer des données directement dans les tables de cette BDD afin de ne pas compromettre l'intégrité des données. Pour modifier ces données il faut utiliser les méthodes de Garradin.
          116  +
          117  +Chaque plugin peut créer une ou plusieurs tables dans cette BDD, elles devront par contre être supprimées à la désinstallation. Dans ce cas un plugin peut modifier directement ses tables.
          118  +
          119  +=== Fichiers ===
          120  +
          121  +Les plugins ne doivent pas créer, modifier ou supprimer de fichiers dans l'arborescence de Garradin.
          122  +
          123  +Les seuls fichiers qu'un plugin devrait modifier sont :
          124  +* du cache : utiliser de préférence l'objet Static_Cache de Garradin, ou faire attention aux collisions de noms ;
          125  +* les squelettes dans le répertoire **www/squelettes/**
          126  +
          127  +Pour enregistrer et récupérer des documents il faut utiliser les méthodes de stockage de fichiers fournies par Garradin.
          128  +
          129  +=== Dans les templates ===
          130  +
          131  +Garradin fournit la lib Template_Lite, déjà chargée par défaut. C'est une version allégée de Smarty 2.
          132  +
          133  +Afficher un template contenu dans le plugin :
          134  +<pre>
          135  +    $tpl->display(PLUGIN_ROOT . '/templates/index.tpl');
          136  +</pre>
          137  +
          138  +Inclure un template de Garradin depuis un template :
          139  +<pre>
          140  +    {include file="admin/_head.tpl"}
          141  +</pre>
          142  +
          143  +Inclure un template du plugin depuis un autre template du plugin :
          144  +<pre>
          145  +    {include file="`$plugin_root`/templates/_nav.tpl"}
          146  +</pre>
          147  +
          148  +Faire un lien vers une autre page du plugin :
          149  +<verbatim>
          150  +    <a href="{plugin_url file="liste.php"}">Liste des trucs</a>
          151  +</verbatim>
          152  +
          153  +Inclure une feuille de style CSS supplémentaire sur les pages du plugin (chemin relatif à la racine du plugin) :
          154  +<pre>
          155  +    $tpl->assign('plugin_css', 'styles/bleu.css');
          156  +</pre>