Linea21

h1. Système de Plugins

h2. Téléchargement d'un plugin

Pour télécharger un plugin, utilisez svn. Par exemple : 

<pre>

svn co http://dev.linea21.com/svn/linea21-plugins/trunk/l21_gotoTop/

</pre>

La liste des plugins disponibles est accessible via le "dépôt":http://dev.linea21.com/projects/linea21/repository/linea21-plugins?path[]=trunk.

h2. Installation d'un plugin

*Pré-requis* : Avant d'installer un plugin, vous devez vous assurer que le *MOD_PLUGIN* est bien actif. Pour cela, depuis l'interface d'administration, allez sur _Configurer_ > _Système_. Déplier l'onglet _Configuration système (define_release)_. Passez en mode édition et changez la valeur de *MOD_PLUGIN* à 1. Enregistrez les modifications.

Dès lors que le *MOD_PLUGIN* est activé, le sous-menu _Plugins_ apparaît dans l'onglet _Configurer_.

# Placez le plugin téléchargé (par exemple _l21_gotoTop_) dans le dossier /plugins/ de l'application

# Donner les permissions nécessaires à l'utilisateur apache sur le dossier. Cette étape est nécessaire car l'application doit pouvoir écrire dans le répertoire. Par exemple :

  * <code>chown www-data:www-data /plugins/l21_monplugin/</code>

  * <code>chmod -R 0755 /plugins/l21_monplugin/</code>

# Vous pouvez à présent vous rendre sur la page des plugins en cliquant sur _Configurer_ > _Plugins_. Le plugin nouvellement installé doit apparaître. Vous devez à présent l'activer en cliquant sur le lien adéquat. Votre plugin est installé!

h2. Architecture d'un plugin

L'architecture d'un plugin doit se conformer à quelques règles.

# D'abord en ce qui concerne le nommage, le plugin doit nécessairement être préfixé de *l21_*

# Il doit contenir un fichier <code>plugin.xml</code> qui renseignera les méta-informations (nom, auteur, compatibilité, date de sortie, portée du plugin ...)

# Il doit nécessairement disposé d'un fichier nommé <code>__init__.php</code>. Ce fichier sera exécuté à chaque appel de page. C'est lui qui instancie le plugin et permettra donc son exécution.

# Si le plugin fait appel à des fichiers de langue, il doit impérativement reproduire la structure applicative. Il contient alors un répertoire nommé languages et autant de sous-répertoires pour les langues (par exemple _fr_ et _en_). Tous les fishiers contenus dans les sous-répertoires seront chargés lors de l'instanciation du plugin.

# La présence d'un fichier <code>__install__.php</code> permettra lors de l'installation du plugin d'effectuer des actions relatives à sa mise en oeuvre, par exemple, l'ajout d'une table dans la base de données, la modification d'un fichier, ...

# Le fichier <code>__uninstall__.php</code> permettra lors de la désactivation du plugin d'effectuer des actions particulières : par exemple, la suppression d'une table dans la base de données ou d'un fichier, ...

Pour le reste, vous avez une totale liberté dans l'organisation de votre plugin. Veillez toutefois à proposer une structure claire, afin que celui-ci puisse être amélioré ou repris par un autre utilisateur.

h2. L'objet plugin

Chaque plugin est instancié par la classe "plugin":http://dev.linea21.com/projects/linea21/repository/changes/trunk/v1/class/class.plugin.php. Les propriétés de l'objet sont ainsi rendues disponibles via la variable globale <code>$plug</code>.

Par exemple : 

<pre><code class="php">

echo $plug->getVar('name');

echo $plug->getVar('shortname');

// renverra le nom du plugin

// puis le nom du plugin privé du préfixe l21_

</code>

</pre>

Référez-vous à "la classe":http://dev.linea21.com/projects/linea21/repository/changes/trunk/v1/class/class.plugin.php pour connaître les attributs de l'objet et les méthodes qui y sont liées.

h2. Balises standards

* _pluginname_ : nom du plugin

* _description_ : description du plugin au format texte

* _version_ : numéro de version

* _date_ : date de la version du plugin

* _compatibility_ : versions avec lesquelles le plugin est compatible

* _author_ : nom de l'auteur

* _homepage_ : Lien vers la page web de l'auteur

* _default_language_ : Langage utilisé par défaut par le plugin (dans le cas où la langue courante n'est pas pris en charge)

* _apps_ : La balise <apps> définit la portée du plugin. Elle peut comporter un ou plusieurs tags enfants (<app>), selon que le plugin est utile à l'interface publique, à l'interface d'administration ou au deux -comme dans l'exemple ci-dessous.

* _image_ (optionnelle) : nom du fichier pointant vers l'image illustrant le plugin

* _settings_ (optionnelle) : prend la valeur _0_ ou _1_. Indique si le plugin est configurable ou non. S'il l'est, l'auteur du plugin doit fournir la logique applicative et l'interface (fichier _index.php_).

* _load_on_settings_ (optionnelle) : prend la valeur _0_ ou _1_. Indique si le plugin doit être éxécuté lors de la consultation de la page de configuration.

* _restricted_edition_ (optionnelle) : par défaut, les fichiers de plugins sont accessibles en lecture/écriture depuis l'éditeur en ligne. La balise <restricted_edition> permet de spécifier des fichiers à ignorer, via l'utilisation de balises enfants <file>

h2. Exemple de fichier plugin.xml

<pre><code class="xml">

<?xml version="1.0" encoding="UTF-8"?>

<plugin>

	<pluginname>l21_gotoTop</pluginname>

	<description>Add a go to Top button on each pages</description>

	<version>1</version>

	<date>22-01-2012</date>

	<compatibility>1.5 +</compatibility>

	<author>Simon Georget</author>

	<homepage>http://www.empreinte-urbaine.eu</homepage>

	<default_language>fr</default_language>

        <image>plugin.png</image>

	<apps>

		<app>public</app>

		<app>admin</app>

	</apps>

	<restricted_edition>

		<file>config.php</file>

		<file>mypaswwords.php</file>

	</restricted_edition>

</plugin>

</code>

</pre>

h2. Exemple de l'architecture d'un plugin 

La capture d'écran ci-dessous décrit l'architecture du plugin l21_gotoTop affichant une flèche permettant à l'utilisateur de revenir en haut de page à tout moment.

!plugin.png!

Pour accéder au code source du plugin, "suivez le lien":http://dev.linea21.com/projects/linea21/repository/show/trunk/v1/plugins/l21_gotoTop.

h2. Le stockage et l'accès aux données d'un plugin

Depuis la version 1.6, Linea21 permet de stocker des informations relatives au plugin en base de données. La table l21_plugins permet de stocker un tableau sérialisé de paramètres dans le champ _plugin_values_ (au format TEXT).

Les méthodes _storesValues()_ et _retrieveValues()_ disponibles dans la classe _class.plugin.php_ permettent aisément de manipuler les données.

!plugin_db.png!