Changes to "Plugins" between 2014-03-21 04:02:52 and 2015-05-10 23:40:07

1
2

3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134


1




































































































































-
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
<h1>Les plugins dans Garradin</h1>

La doc est dans : doc/dev/plugins.skriv
  *  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)

<h4>Exemples de plugins possibles</h4>

  *  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
  
<h3>Structure archive PHAR</h3>

  *  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
 
<h3>Contenu de garradin_plugin.ini</h3>

<pre>
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)
</pre>

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

<h3>Méthodes de l'objet \Garradin\Plugin</h3>

  *  __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

<h3>Dans le plugin : templates</h3>

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 :
<pre>
    $tpl->display(PLUGIN_ROOT . '/templates/index.tpl');
</pre>

Inclure un template de Garradin depuis un template :
<pre>
    {include file="admin/_head.tpl"}
</pre>

Inclure un template du plugin depuis un autre template du plugin :
<pre>
    {include file="`$plugin_root`/templates/_nav.tpl"}
</pre>

Faire un lien vers une autre page du plugin :
<verbatim>
    <a href="{plugin_url file="liste.php"}">Liste des trucs</a>
</verbatim>

Inclure une feuille de style CSS supplémentaire sur les pages du plugin (chemin relatif à la racine du plugin) :
<pre>
    $tpl->assign('plugin_css', 'styles/bleu.css');
</pre>

<h2>Plugins officiels</h2>

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)

<h3>Règles de base à respecter par les plugins officiels</h3>

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/)