Overview

Artifact ID: ff1fac74f42294cc269b99c7e0adf41494a84f60
Page Name:Plugins
Date: 2014-03-21 04:02:52
Original User: bohwaz
Parent: 8d7cadf0d9fa63dde430fa5c75d50021862e3b70 (diff)
Next 23f9a7531cd8b7bcc23c4dcaaaf00f1753360911
Content

Les plugins dans Garradin

  • Chaque plugin est une archive PHAR de PHP (voir structure archive plus bas)
  • Les plugins étendent ou complètent les fonctionnalités de Garradin, mais ne les remplacent pas et ne peuvent pas modifier la base de données directement
  • Toute modification de données doit s'effectuer via les objets et méthodes de Garradin pour éviter tout problème d'incohérence de données
  • Les plugins peuvent modifier le comportement de Garradin via des signaux/hooks (à venir)

Exemples de plugins possibles

  • Export dans un format spécifique
  • Création PDF de cartes d'adhérent
  • Gestion de stock
  • Point de vente (caisse)
  • Import depuis un format spécifique
  • Envoi de mails au format HTML

Structure archive PHAR

  • garradin_plugin.ini : informations sur le plugin
  • www/admin/index.php (optionnel) : affiché quand on clique sur le plugin dans le menu admin (si menu=1)
  • install.php (optionnel) : appelé lors de l'installation du plugin
  • upgrade.php (optionnel) : appelé lors de la mise à jour du plugin, qu'elle soit une mise à jour vers une version supérieure ou inférieure (downgrade)
  • uninstall.php (optionnel) : appelé lors de la suppression du plugin
  • signals.php (optionnel) : appelé quand un signal enregistré est activé
  • www/config.php (optionnel, si le plugin peut être configuré) : appelé depuis la page de configuration des plugins
  • config.json (optionnel, si le plugin peut être configuré) : configuration par défaut du plugin

Contenu de garradin_plugin.ini

nom="Nom du plugin"
description="Description courte du plugin"
auteur="Nom de l'auteur"
url="URL du site du plugin"
version="Numéro de version"
menu=0 ; ou 1 pour qu'une sous-entrée apparaisse dans le menu des plugins sur la partie privée (admin), en ce cas le fichier www/admin/index.php est obligatoire
config=0 ; ou 1 pour que le plugin ait une configuration personnalisable, dans ce cas il faut fournir les fichiers config.json (configuration par défaut) et config.php (modification de la configuration par l'utilisateur)

Ces informations sont enregistrées dans la base de données de l'association

Méthodes de l'objet \Garradin\Plugin

  • __construct(string $id)
  • setConfig(string $key, string $value) : enregistre la configuration du plugin, si $value est null alors cette clé est effacée de la configuration
  • getConfig(string $key) : récupère la valeur de la clé $key pour la configuration du plugin
  • getInfos() : renvoie les informations enregistrées sur le plugin
  • upgrade() : mise à jour du plugin
  • needsUpgrade() : le plugin doit-il être mis à jour ?
  • uninstall() : désinstaller le plugin
  • id() : renvoie l'identifiant du plugin
  • path() : renvoie le chemin vers l'archive PHAR du plugin

Dans le plugin : templates

Garradin fournit la lib Template_Lite, déjà chargée par défaut. C'est une version allégée de Smarty 2.

Afficher un template contenu dans le plugin :

    $tpl->display(PLUGIN_ROOT . '/templates/index.tpl');

Inclure un template de Garradin depuis un template :

    {include file="admin/_head.tpl"}

Inclure un template du plugin depuis un autre template du plugin :

    {include file="`$plugin_root`/templates/_nav.tpl"}

Faire un lien vers une autre page du plugin :

    <a href="{plugin_url file="liste.php"}">Liste des trucs</a>

Inclure une feuille de style CSS supplémentaire sur les pages du plugin (chemin relatif à la racine du plugin) :

    $tpl->assign('plugin_css', 'styles/bleu.css');

Plugins officiels

Garradin offre deux possibilités d'installer des plugins :

  • simplement en copiant un fichier PHAR dans le répertoire 'plugins' de Garradin
  • en passant par un "répertoire" officiel, sorte d'appstore des plugins Garradin

Ce répertoire permet de télécharger et installer les plugins en un clic depuis l'interface de Garradin. Par la suite les plugins sont mis à jour automatiquement depuis ce répertoire quand une mise à jour est disponible.

Pour intégrer le répertoire des plugins officiels disponibles directement depuis Garradin le plugin doit :

  • être sous licence libre (compatible FOSS : GPL, AGPL, BSD, etc.)
  • respecter les règles présentées ci-dessous

Son code doit être lisible et clair, peu importe la convention de codage utilisé.

Fonctionnement de l'installation de plugin :

  • L'intégrité d'un plugin est vérifié en comparant son empreinte SHA-1 à celle contenue dans la liste fournie par le site de Garradin dans la liste des plugins officiels
  • Si le plugin figure dans la liste mais son intégrité n'est pas correcte il ne sera pas possible d'installer le plugin
  • Si le plugin ne figure pas dans la liste un message d'alerte et de demande de confirmation sera affiché avant installation (plugin non-officiel)

Règles de base à respecter par les plugins officiels

Sur les interactions avec Garradin :

  • Un plugin NE DOIT PAS modifier, patcher ou transformer les fichiers fournis dans la distribution de Garradin (cette restriction pourrait être ôtée dans le futur) et ce afin de garantir le fonctionnement et du plugin et de Garradin lors d'une mise à jour de ce dernier
  • Un plugin NE DOIT PAS ajouter, copier ou supprimer des fichiers dans l'arborescence de Garradin

Sur les interactions avec la base de données :

  • Un plugin PEUT créer une nouvelle table dans la base de données de Garradin à l'installation, mais il DOIT alors la supprimer à la désinstallation
  • La table DOIT se nommer plugin_<identifiant du plugin>_<nom de la table>
  • Un plugin NE DOIT PAS créer de base de données indépendante de celle de Garradin (hormis une utilisation de type cache/index)
  • Un plugin PEUT lire les données des tables de Garradin librement
  • Un plugin NE DOIT PAS modifier directement les tables de Garradin, seulement ses propres tables
  • Un plugin PEUT lire, modifier et supprimer les données de la base Garradin via les méthodes de Garradin

Sur les fichiers :

  • Un plugin NE DOIT PAS créer, éditer ou supprimer de fichier autre que temporaire, cache ou index
  • Pour créer et gérer des fichiers un plugin DOIT utiliser la gestion de documents de Garradin

Sur la communication à l'extérieur :

  • Un plugin ne devrait pas contacter un serveur distant sauf besoin spécifique.
  • Un plugin NE DOIT PAS contacter un serveur distant à des fins statistiques ou publicitaires.
  • Un plugin NE DOIT PAS transmettre des informations sur la base de données ou son contenu à un tiers, sauf cas spécifique.
  • Le plugin DOIT intégrer toutes ses dépendances dans l'archive, hormis celles qui sont déjà incluses avec Garradin.

Sur les squelettes :

  • Un plugin PEUT modifier, ajouter, supprimer, etc. des fichiers dans le répertoire www/squelettes/ (mais pas squelettes_dist/)