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 relative à sa mise en oeuvre, par exemple, l'ajout d'une table dans la base de données, la modification 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 autorisées

* _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!