Utiliser les plugins

I Les notions de plugin et de point d'accès

Un plugin est une fonction PHP qui n'est pas appelée directement par un script, mais via les paramétrages effectués dans le registre. Les plugins permettent de rendre le logiciel extrêmement modulable. En effet, on pourra paramétrer dans le registre quel plugin utiliser pour exécuter telle ou telle tâche. Par ailleurs, on pourra également fournir des paramètres au plugin via le registre.

A proprement parler, le plugin est un script (et une fonction). Mais on peut également désigner par ce nom les informations du registre permettant d'exécuter cette fonction (emplacement du fichier, nom de la fonction, paramètres). Ces informations sont stockées dans profiles/defaut/plugins/plugins.

On désige en revanche par point d'accès les informations fournies pour appler le plugin. On peut appeler un même plugin à des dizaines d'endroits différents, à chaque fois en fournissant des paramètres différents.

II Appeler un plugin dans un script

Pour appeler un plugin dans un script on utilise la fonction

array applique_plugin (point_d_acces, parametres);

La fonction retourne toujours une Array ayant la forme
$retour["succes"] => 0 ou 1
$retour["erreur"] => message d'erreur éventuel
$retour["resultat"] => le résultat (qui lui-même est souvent une array)

Le 2e argument, $parametres est toujours une array (éventuellement vide)

Le 1e argument est le point d'accès. Il peut être une chaîne de caractère ou une array.

Si c'est une chaîne de caractère, WB ira chercher le point d'accès dans le registre à partir de profiles/defaut/plugins/points_acces (cette possibilité est dépréciée)

Si c'est une array, elle doit avoir la forme :
> $point_d_acces["nom_plugin"] => chaine de caractères indiquant l'emplacement du plugin (de la forme catalogue/import_export/main/biblio/unimarc_standard)
Ce chemin peut indiquer soit l'emplacement de la définition du plugin dans le registre à partir de profiles/defaut/plugins/plugins soit l'emplacement du script à partir du répertoire  include/plugins.
(voir la distinction entre plugins simples et plugins virtuels)

> $point_d_acces["parametres"] => une array contenant les paramètres passés au plugin PAR LE SCRIPT. (se rajoute aux paramètres passés via le registre)

La bonne pratique veut que le point d'accès (qu'il s'agisse d'une chaîne ou d'un tableau) soit lui-même défini dans le registre. SOIT le plugin est appelé dans une page, auquel cas, on indiquera le point d'accès dans le noeud _parametres de la page, SOIT il est appelé depuis un autre plugin, auquel cas on indiquera le point d'accès dans le noeud parametres du plugin.

Dans les 2 cas, l'utilisation dans le script est très simple, car les variables définies dans les paramètres sont directement accessibles dans le script, on aura donc quelquechose du genre :
Dans un plugin : 
$tmp=applique_plugin ($parametres["plugin_pour_faire_tel_truc"], array ("param1"=>"tutu", "param2"=>"toto"));
Dans une page :
$tmp=applique_plusgin ($GLOBALS["affiche_page"]["parametres"]plugin_pour_faire_tel_truc"], array ("param1"=>"tutu", "param2"=>"toto"));

III Créer un plugin

1) Créer le script

Un plugin est tout d'abord une fonction contenue dans un script. l'emplacement et le nom du script ainsi que le nom de la fonction sont importants et régis par des conventions.

Les plugins sont stockés dans le répertoire include/plugins et dans ses sous-répertoires.

Si un plugin est stocké dans le répertoire include/plugins/a/b/c et s'appelle toto.php alors la fonction devra avoir pour nom  function plugin_a_b_c_toto ($parametres) { }

Les paramètres sont toujours fournis au plugin sous la forme d'une unique array.

Un plugin retourne toujours une array de la forme
$retour["succes"] => 0 ou 1
$retour["erreur"] => message d'erreur éventuel
$retour["resultat"] => le résultat (qui lui-même est souvent une array)

2) Déclarer un plugin dans le registre

Il existe plusieurs solutions pour déclarer le plugin dans le registre. Plugins simples (le plugin est équivalent au script) ou plugins virtuels (plusieurs plugins utilisent le même script avec des paramètres différents)

a) Plugin simple

Dans un plugin simple, il y a identité entre le plugin et le script contenant la fonction. Par conséquent, l'arborescence dans le registre correspondra exactement à l'arborescence des fichiers.
Si le plugin toto.php se trouve dans le répertoire a/b/c, alors dans le registre, le plugin sera défini dans :
profiles/defaut/plugins/plugins/a/b/c/toto

Dans ce noeud, on déclarera simplement un noeud parametres pour spécifier les paramètres du plugin.

Si aucun paramètre ne doit être défini au niveau du plugin, on peut même se dispenser de définir le plugin. Dans le registre. dans ce cas le nom du plugin fourni dans le point d'accès (pour la fonction applique_plugin()) correspond à l'emplacement du fichier plugin.

b) Plugin virtuel

On parle de plugins virtuels quand plusieurs plugins utilisent le même script (et la même fonction) mais avec des paramètres différents. Dans ce cas, le nom du plugin (son arborescence dans le registre) ne correspond pas à l'emplacement du script dans l'arborescence des fichiers.

Le plugin sera défini dans profiles/defaut/plugins/plugins (et ses noeuds enfants)
Par exemple si on définit un plugin appelé "a/b/c/toto"

il faudra créer les noeuds :
profiles/defaut/plugins/plugins/a/b/c/toto/chemin_fichier
profiles/defaut/plugins/plugins/a/b/c/toto/nom_fonction
profiles/defaut/plugins/plugins/a/b/c/toto/parametres

Le noeud "chemin_fichier" contiendra l'emplacement du script à partir du répertoire include/plugins
Le noeud "nom_fonction" contiendra le nom du script (sans le ".php").

Par exemple si on a un script "toto.php" qui se trouve dans include/plugins/a/b/c, on aura :
chemin_fichier => a/b/c
nom_fonction => toto

IV Passer des paramètres au plugin

On peut passer des paramètres au plugin à 3 moments différents :
> Dans le script qui appelle le plugin
> Au niveau du point d'accès (dans le registre)
> Au niveau du plugin (dans le registre)

La logique de ces 3 moments est différente.

On définira dans le registre au niveau du plugin les paramètres qui sont propres au plugin. Chaque appel au plugin fera appel à ces même paramètres quel que soit le script qui l'appelle. C'est particulièrement utile dans le cas des plugins virtuels.

On définira dans le registre au niveau du point d'accès les paramètres qui sont spécifiques à telle utilisation du plugin, à un moment donné.

On définira au niveau du script les paramètres qui ne peuvent être définis dans le registre, souvent parce qu'ils sont dynamiques (un pointeur vers un fichier, un objet XML...)

Les paramètres passés à ces 3 moments sont fusionnés et utilisables dans le plugin via le tableau $parametres. Il est possible de surcharger des paramètres  avec la priorité suivante : 1) script 2) point d'accès 3) plugin.

Par exemple si on a défini le paramètre toto = 1 dans le point d'accès et toto = 2 dans le plugin, alors $parametres["toto"] vaudra 1 dans le plugin.

V Définir des paramètres dans le point d'accès ou créer un plugin virtuel ?

Pratiquement cela revient au même d'avoir un seul plugin et de fournir des paramètres différents au niveau du point d'accès ou de créer plusieurs plugins virtuels avec des paramètres différents et de les appeler sans fournir de paramètres.

En réalité, cela dépendra de la réponse à la question suivante : "Suis-je amené à utiliser plusieurs fois un même plugin avec les mêmes paramètres ?" Si la réponse est oui, il vaut mieux créer un plugin virtuel. Cela évitera d'avoir à répéter plusieurs fois les mêmes paramètres au niveau des points d'accès. Et surtout, en cas de modification, on n'aura à le faire qu'une fois.

En revanche, si on n'utilise qu'une seule fois un plugin avec certains paramètres, on peut définir ces derniers au niveau du point d'accès et ne conserver qu'un seul plugin.

VI Intégrer les résultats d'un plugin dans les paramètres

Parfois, il peut être intéressant de faire figurer, dans les paramètres d'un plugin, le résultat d'un autre plugin.

Pour cela, on peut utiliser dans le plugin la fonction plugins_2_param ($tableau, $parametres) {}.

Par exemple, on a dans le registre les paramètres d'un plugin :
[intitule]=>toto
[valeur]=>tutu
[!!liste_champs]=>[nom_plugin]=>aa/bb/cc, [parametres]=>???

Si dans le plugin on $parametres = appelle plugins_2_param ($parametres, array());

on obtiendra $parametres = 
[intitule]=>toto
[valeur]=>tutu
[liste_champs]=> XXXX (ce que retourne le plugin aa/bb/cc) 

Pour cela, il faut préfixer le noeud du registre par "!!"