Qu’est-ce qu’un plugin ? Principes et création.

Cette documentation décrit uniquement le fonctionnement pour SPIP 2.0

Nota : D’autres documentations explicatives existent sur spip.net :
 Installer un plugin
 Réaliser un premier plugin
 Etendre SPIP

Créer un plugin

Pour créer un plugin, il suffit simplement de créer un dossier au nom de votre plugin dans le répertoire plugins/ de SPIP. Il vous faut créer ce répertoire s’il n’est pas présent.

Pour que le plugin soit connu de SPIP, il faut que le dossier de votre plugin contiennent un fichier plugin.xml, composé d’un certain contenu, décrit plus loin dans cette documentation.

A partir de là, il y a trois moyens principaux donnés aux plugins pour transmettre des informations à SPIP :

1. la surcharge et création de fichiers
2. le contenu du fichier plugin.xml
3. les points d’entrées de SPIP (appelés pipelines)

Surcharge et création de fichiers

Depuis longtemps, SPIP permet de surcharger ses fichiers et d’en utiliser de nouveaux les installant dans le dossier squelettes/ ou en ajoutant des dossiers dans le chemin (ou path) de SPIP via la globale PHP dossier_squelettes ou par la constante PHP _SPIP_PATH, par exemple avec cette ligne dans le fichier config/mes_options.php :

Lorsque l’on demande un fichier à SPIP (fichier php ou un squelette), SPIP va chercher le fichier dans l’ordre des chemins. S’il ne le trouve pas dans le répertoire
 squelettes/, il cherchera dans
 mon_dossier/,
 dist/,
 prive/, puis
 ecrire/.

Lorsqu’un plugin est activé, celui-ci s’ajoute automatiquement dans le chemin de SPIP. Ainsi, lorsque SPIP cherche un fichier, il regardera (si l’on reprend l’exemple précédent) dans
 squelettes/,
 mon_dossier/,
 plugins/le_plugin/,
 dist/,
 prive/, puis dans
 ecrire/.

Lorsque plusieurs plugins sont actifs, SPIP cherchera dans les plugins par ordre alphabétique par rapport au nom du dossier. plugins/attributs/ sera traité avant plugins/crayons.

Cependant, les plugins peuvent necessiter ou utiliser d’autres plugins. Par exemple, le plugin Crayons peut être configuré avec le plugin CFG. Pour cela, crayons possède une ligne spéciale indiquant sa dépendance optionnelle à CFG dans le fichier plugin.xml.

Un plugin qui dépend d’un autre passe alors avant lui dans les chemins de SPIP. Cela permet au plugin de surcharger des fichiers du plugin dont il dépend.

Dans l’exemple précédent, l’ordre de lecture des répertoires serait :
 squelettes/,
 mon_dossier/,
 plugins/attributs/,
 plugins/crayons/,
 plugins/cfg/,
 dist/,
 prive/,
 ecrire/.

Quels répertoires pour les fichiers des plugins ?

Voir aussi :
 Etendre SPIP
 Les différents points d’insertion d’un plugin

Vous êtes libre de l’organisation du répertoire de votre plugin, cependant, il est préférable d’utiliser les mêmes nommages de répertoires que SPIP, ceci pour faciliter la compréhension et la maintenance du plugin.

Voici quelques répertoires et leurs fonctions (pour les plugins) :
 action/ : actions généralement sécurisées modifiant le contenu de la base de données
 balise/ : déclaration de balises SPIP dynamiques. La plupart des balises peuvent être déclarées dans le fichier de fonctions du plugin. Les autres balises fournies par SPIP sont déclarées dans public/balises.php.
 base/ : déclaration, installation, et mise à jour et désinstallation de la structure de la base de données ; procédures d’installation et de désinstallation du plugin
 exec/ : affichage de pages dans l’interface privé,
 genie/ : taches périodiques (cron),
 inc/ : librairies de fonctions,
 javascript
 lang/ : fichiers de lang pour le multilinguisme,
 public/ : compilateur de SPIP, déclarations d’exceptions sur les champs de tables SQL
 req/ : traducteurs des fonctions d’abstractions SQL vers les serveurs de base de donnée (MySQL, PostGres, SQlite)
 urls/ : gestion des urls publiques des pages de SPIP
 xml/ : interpreteur XML de SPIP

Plugin.xml

Voir aussi : Le fichier plugin.xml

Les plugins ont des possibilités supplémentaires par rapport à un simple dossier squelettes. Ils peuvent utiliser leur propres fichiers de fonctions ou d’options, peuvent exécuter des procédures lors de leur installation, mise à jour ou désinstallation et ils peuvent utiliser des points d’entrées de SPIP.

Tout cela doit être déclaré dans le fichier plugin.xml. C’est le fichier qui décrit le plugin, son nom, sa version, sa description, son auteur, sa licence ainsi que les points d’entrées de SPIP qu’il utilise.

Décrivons la syntaxe, en utilisant le fichier (simplifié) du plugin Crayons (voir le code original) :

Il faut tout s’abord encadrer les paramètres contenus dans plugin.xml par une balise <plugin> :

Les paramètres sont assez nombreux, on pourra trouver :
 nom
 auteur
 version : la version du plugin
 version_base : la version de la structure de la base de donnée du plugin
 etat : stable, test ou en dev
 lien : vers la documentation
 icon
 description
 licence
 fonctions : nom d’un fichier de fonctions chargé au moment des calculs de squelettes
 options : nom d’un fichier d’options chargé à chaque hit
 necessite : dépendance obligatoire d’un autre plugin (ou d’une version de SPIP)
 utilise : dépendance optionnelle
 pipeline : déclaration de l’utilisation de points d’entrées de SPIP par le plugin
 chemin : ’’ ou ’ecrire/’ charger le plugin systematiquement ou seulement dans l’interface privée

Ce qui donne pour le plugin Crayons un fichier xml de la sorte :

Le plugin déclare utiliser 2 pipelines : affichage_final et header_prive, dont les fonctions sont déclarées dans le fichier tetecrayons.php.

Points d’entrées

Voir aussi :
 Se servir des points d’entrées
 Les pipelines
 Création d’un plugin
 Mise en oeuvre de la balise #PIPELINE

Les points d’entrées ou "pipeline" sont des fonctions exécutées par SPIP à certains endroits de son code, dans lesquelles SPIP transmets certains paramètres.

Lorsqu’un plugin a déclaré un pipeline, et que le pipeline en question est appelé, SPIP appelle la fonction du plugin avec les paramètres. La fonction du plugin doit retourner ce qu’elle a reçu, en modifiant (ou non) les paramètres.

Par exemple, le pipeline insert_head permet d’ajouter du contenu dans entre les balises <head> et </head> des pages publiques générées par SPIP. Pour ce pipeline, c’est directement le contenu html ajouté qui est transmis. Un plugin pourra donc l’utiliser de la sorte (en l’ayant déclaré dans le fichier plugin.xml) :