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

Un plugin est un ensemble paquetages de fichiers qui servent à apporter des fonctionnalités supplémentaires à l’écureuil SPIP. Tout ce qui peut être mis dans un dossier squelettes/ peut être proposé sous forme de plugin.

Un plugin peut donc fournir des habillages graphiques, des fonctionnalités d’administrations, des filtres, des modèles, de nouvelles boucles ou critères, gérer de nouvelles tables SQL, etc. Les possibilités d’un plugin dépendent juste de l’imagination de son créateur.

Un plugin doit donc permettre de dire à SPIP qu’il possède de nouvelles fonctionnalités, ou que certains points du fonctionnement de SPIP changent si l’on utilise un plugin.

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) :