Raccourcis : Contenu - rubriques - sous rubriques
EN FR

Il est possible d'ajouter des plugins au coordinateur (le cœur de Jelix, jCoordinator) qui permettent de faire des traitements supplémentaires à différentes étapes de l'exécution d'une action, quelle que soit cette action.

Il est ainsi possible d'effectuer un traitement au démarrage du processus, juste avant l'exécution de l'action, juste après (avant affichage), et en fin de processus.

Les plugins pour le coordinateur sont aussi appelés plugins coord dans le jargon Jelix.

Utilisation d'un plugin coord

Déclaration

Pour activer un plugin coord, vous avez deux choses à faire :

  • bien sûr, déclarer le dépôt contenant le répertoire de votre plugin
  • dans le fichier de configuration d'un point d'entrée indiquer le plugin dans la section [coordplugins], avec comme valeur "1" ou le nom de son fichier de configuration si il en a un (chemin relatif au répertoire de configuration).

Si vous placez votre plugin foo dans votreApplication/plugins/coord/ alors vous devez déclarer comme ceci :



[coordplugins]
foo = foo.coord.ini.php

Ici on indique un fichier de configuration foo.coord.ini.php pour le plugin (le contenu et la structure de ce fichier de configuration dépend totalement du plugin). Dans le cas où votre plugin ne comporte pas de fichier de configuration, vous devez mettre 1 au lieu d'un nom de fichier, comme ceci :


foo = 1

La valeur "1" indique aussi que la configuration du plugin peut être dans la configuration du point d'entrée. Cette configuration doit alors être placée dans une section [coordplugin_<pluginname>] (où <pluginname> est le nom du plugin, comme par exemple [coordplugin_foo]).

  • *Important** : Si vous utilisez plusieurs plugins de coordinateur, l'ordre de déclaration des plugins dans le fichier de configuration a une importance. Ainsi le premier plugin déclaré à la priorité sur les autres. C'est à dire que si ce premier plugin renvoie une action, les autres plugins ne seront pas exécutés. Il convient donc de choisir l'ordre de déclaration des plugins en fonction de la priorité que l'on veut pour chaque plugin. Par exemple si vous considérez que le plugin bar ne peut être exécuté que si le plugin foo n'a pas renvoyé d'action, alors il faudrait les déclarer comme ceci :

[coordplugins]
foo = foo.plugin.ini.php
bar = 1

Configuration

Un plugin coord peut avoir besoin de paramètres de configuration. Ces paramètres peuvent être placé dans une section de la configuration principale, ou un fichier spécifique, ou encore dans des propriétés du contrôleur.

Si il est utilisé un fichier de configuration spécifique, celui-ci doit être alors un fichier de type ini, placé dans FvotreApplication/app/system/@@ et être déclaré dans la configuration comme indiqué précédemment. Le contenu ini sera passé au constructeur du plugin sous forme de tableau (résultat de la fonction php parse_ini_file).

La configuration peut être, comme indiquée plus haut, dans une section [coordplugin_XXX] ou [XXX] d'un des fichiers de configuration générale. Le plugin reçoit alors le contenu de cette section sous forme de tableau associatif.

Si il y a à la fois une section [coordplugin_XXX] (ou [XXX]) et un fichier de configuration spécifique, seul le contenu du fichier de configuration est utilisé. À moins d'indiquer, dans la section [coordplugins], un paramètre XXX.mergeconfig avec une valeur 1 ou on. Dans ce cas, le contenu de [coordplugin_XXX] (ou [XXX]) et du fichier de configuration sont fusionnés (le contenu de [coordplugin_XXX] ou [XXX] étant prioritaire).

Paramètres de plugins

Certains plugins coord peuvent attendre des paramètres qui sont fournis par les contrôleurs. En effet, un plugin peut vouloir tester quelque chose en fonction de l'action.

Par exemple, le plugin coord d'authentification auth va vérifier si l'action demandée nécessite ou non d'être authentifié. Pour cela, on va indiquer dans chaque contrôleur un paramètre pour chaque action, destiné au plugin auth, qui indique cette information.

Ces paramètres sont stockés dans la propriété pluginParams du contrôleur. C'est un tableau associatif. Les clés sont les noms des méthodes, et les valeurs, un tableau contenant tous les paramètres de plugins associés à la méthode (et donc à l'action correspondante). Une clé particulière, '*', indique les paramètres valables pour toutes les méthodes du contrôleur.

Exemple :



public $pluginParams = array(
      '*'=>array('auth.required'=>false)
    );

Indique que toutes les actions du contrôleur ont un paramètre nommé auth.required et valant false.

Voir la documentation du plugin pour savoir quels paramètres vous pouvez utiliser.

Développement d'un plugin coord

Un plugin est en fait une classe qui implémente l'interface jICoordPlugin. Cette classe doit donc implémenter les méthodes suivantes :


    public function __construct($config);
    public function beforeAction($params);
    public function beforeOutput();
    public function afterProcess ();

Le constructeur reçoit la configuration du plugin.

La méthode beforeAction() reçoit les paramètres de plugins déclarés dans le contrôleur. Elle peut renvoyer null si tout est ok ou alors un sélecteur d'action, jSelectorAct, si il faut exécuter une autre action que celle prévue.

La méthode beforeOutput() sera appelée après exécution de l'action.

Le méthode afterProcess() sera appelée en fin de traitement (après affichage donc).

Cette classe est à placer dans un dépôt de plugins. Par exemple, le répertoire plugins/ de votre application. Ou alors dans un répertoire plugins/ d'un module. Le sous répertoire dans lequel est placé le plugin doit porter le nom du plugin, et la classe doit suivre un nommage particulier. Si le plugin s'appelle exemple, alors :

  • le répertoire du plugin sera plugins/coord/exemple/
  • le fichier contenant la classe du plugin devra être plugins/coord/exemple/exemple.coord.php
  • le nom de la classe du plugin devra être exempleCoordPlugin, implémentant l'interface jICoordPlugin

Remplacement d'un plugin par un autre

Il peut être utile pour un plugin de se faire passer pour un autre. La première façon de faire est d'indiquer le nom du plugin qu'il remplace, dans un paramètre de configuration se terminant par .name.

Exemple :


[coordplugins]
cas=cas.coord.ini.php
cas.name=auth

Ici on active le plugin ©as, mais il sera connu sous le nom auth.

Le plugin remplacé ne doit bien entendu pas être activé (donc pas présent dans [coordplugins]).

Autre solution, disponible depuis Jelix 1.7.9 : il est possible d'indiquer une classe spécifique pour un plugin donné, dans un paramètre de configuration se terminant par .class.


[coordplugins]

auth=auth.coord.ini.php
auth.class=casCoordPlugin

La classe peut être celle d'un autre plugin, ou dans un namespace quelconque et dans ce cas, elle doit être pouvoir être chargée automatiquement.