SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [vi] [zh] Espace de traduction

Télécharger

Réaliser un premier plugin

Août 2006 — mis à jour le : Août 2010

Toutes les versions de cet article :


On crée un plugin au même endroit qu’on installe ceux qu’on peut récupérer et déjà prêts à fonctionner (Voir « Installer un plugin »).

Le système de plugin s’appuie sur la recherche de chemins connus dans une liste bien précise. Les technophiles appelleront ça SPIP_PATH (cf. Où placer les fichiers de squelettes ?). L’activation, ou non, d’un plugin décide de l’ajout de son répertoire associé dans cette liste. On devra donc, pour réaliser son premier plugin, créer :

-  Un répertoire plugins/ à la racine du site. La conséquence directe de cette action est d’activer l’interface de gestion des plugins. Le premier symptôme étant l’apparition du bouton « Gestion des plugins » dans le menu « Configuration » de l’interface privée (en mode interface complète uniquement)


-  Un sous-répertoire mon_premier_plugin/ pour le plugin à réaliser.

Pour indiquer à SPIP ce qu’est censé faire le plugin, celui-ci est décrit par un fichier, qui porte le nom plugin.xml, qu’on créé dans le répertoire même du plugin. Il s’agit d’un fichier à la syntaxe stricte mais relativement simple que voici :

Il s’agit d’un fichier contenant les seules balises obligatoires.

-  La balise nom peut être internationalisée grâce à la balise multi (exemple : <nom><multi>My first plugin[fr]Mon premier plugin</multi></nom>). C’est le titre du plugin.
-  La balise version est purement informative. Il n’y a pas de règle précise pour gérer les numéros de version. Il appartient au développeur de les gérer lui-même. Dans l’avenir, il est toutefois possible que cette valeur serve à gérer d’éventuelles dépendances et un minimum de cohérence entre SPIP et les plugins...
-  La balise prefix est cruciale. Il est tout d’abord important de s’assurer de l’unicité de cette valeur parmi tous les plugins que vous installez. Il définit ensuite le préfixe des fonctions que vous allez programmer en php et qui seront les éléments moteurs du plugin. Ainsi, si plusieurs plugins cohabitent avec des fonctions aux traitements similaires, il sera impossible qu’elles provoquent des erreurs à cause de leurs noms. C’est ce qu’on appelle aussi un « espace de noms ».

Bien que ne produisant aucun effet pour le moment, ce minimum permet déjà d’activer le plugin dans l’interface :

Pour ce faire, cochez la case en face du nom du plugin et cliquez sur le bouton « valider » en bas. La zone du titre est grisée.

Amusez-vous à retirer l’une ou l’autre de ses balises pour constater que SPIP peut vous indiquer ce qui manque ou tout simplement ne pas fonctionner.

*-*-*

Il est possible de placer d’autres éléments dans un fichier plugin.xml :

-  La balise <etat> : 4 valeurs possibles. En l’absence de cette balise, ou si elle est présente mais vide, le plugin est considéré comme "en développement". Le fonctionnement du plugin n’est aucunement influencé par la valeur de cette balise. À noter qu’une puce colorée permet de reconnaître l’état d’un coup d’œil.

EtatPuceSignification
dev noire En cours de développement. Nombreux bugs possibles. Ne fonctionne peut-être pas.
test orange La fonction principale est opérationnelle et est à essayer. Les développeurs comptent sur nous pour remonter des commentaires sur d’éventuelles erreurs ou des remarques sur l’ergonomie d’une interface graphique, par exemple.
stable verte Complètement opérationnel. Sans bug, en théorie.
experimental rouge C’est l’aventure !

-  Les balises <auteur> et <description> sont facultatives et fonctionnent comme les textes d’un article (tous raccourcis autorisés) et servent à fournir des informations succintes sur le plugin. Ainsi le code :

aura pour conséquence d’afficher :

Notez qu’il est nécessaire de coder les caractères accentués avec des entités HTML (&eacute; pour é, par exemple).

*-*-*

Si vous placez au même niveau que plugin.xml un fichier squelette.html, votre plugin une fois activé, permet l’utilisation du dit squelette qui sera utilisable en l’appelant dans votre navigateur avec la notation « usuelle » : votresite.net/spip.php?page=squelette. Il s’agit là d’un simpliste mais premier exemple de surcharge de fichier. Ce principe sera approfondi dans un autre tutoriel.

*-*-*

Pour illustrer cette démonstration, nous allons réaliser un plugin dont le but est de colorer d’une manière particulière, chaque occurrence du mot « spip » dans un texte. Nous allons pour cela, placer dans le répertoire du plugin les 2 fichiers utiles et informer SPIP de leurs noms via quelques balises supplémentaires dans le fichier XML :

Voici la description des 2 balises ajoutées :

-  <fonctions> : contient le nom d’un fichier qui sera chargé à chaque recalcul. C’est l’équivalent pour chaque plugin, du fichier mes_fonctions.php. Il n’est donc utilisé que pour le site public, puisque qu’il n’est appelé qu’en cas de calcul du cache. On y mettra typiquement des filtres ou des définitions de balises, de critères.
-  <options> : contient le nom d’un fichier qui sera chargé à chaque appel de page . C’est l’équivalent pour chaque plugin, du fichier mes_options.php. Il est aussi utilisé dans l’interface privée à chaque appel de page.

Créez les 2 fichiers avec le contenu ci-dessous :

exemple_fonctions.php :

exemple_options.php :

Attention ! Il y a des noms de fichier qu’il est préférable ne pas utiliser dans le cas des plugins : nous sommes dans le cadre d’une liste de répertoires connus et SPIP s’arrête toujours au premier fichier trouvé. Si le fichier de la balise <fonctions> s’appelle mes_fonctions.php, il y aura confusion avec le fichier de votre dossier squelettes, s’il existe et surtout, si plusieurs plugins sont programmés avec ce nom de fichier, le système risque de se perdre... idem pour mes_options.php, qu’il faut réserver au noyau de SPIP ainsi que pour les fichiers de langues local_xx.php auxquels on préfèrera une autre méthode décrite dans un tutoriel consacré à la surcharge de code.

Donc : évitez les noms « communs » tels que mes_fonctions.php et mes_options.php.

Nous verrons dans un autre article comment surcharger les répertoires de SPIP. Sachez déjà que des noms de répertoires tels que « modeles », « formulaires », « inc », « action » etc... sont à utiliser à bon escient.

Enfin, prenez garde à être très exact dans la saisie des noms de fichier dans plugin.xml, l’interface de gestion est très capricieuse pour l’ajout des dernières balises (messages d’erreur qui plantent le serveur...)

Bref, voilà, ce plugin apporte un nouveau filtre pour vos squelettes. Essayez [(#TEXTE|colore_spip)] dans article.html par exemple.

*-*-*

On installe tous les plugins dans le répertoire plugins/, mais on peut créer des sous-répertoires pour catégoriser les plugins qu’on installe ou développe.

Ainsi, pour l’arborescence suivante :

plugins/
  |
  |-- mon_premier_plugin/
  |-- mes_raccourcis_supplementaires/
         |
         |-- raccourcis_2/
         |-- raccourcis_3/
  |-- mes_autres_plugins/
         |
         |-- raccourcis_4/
         |-- raccourcis_5/

l’interface de gestion aura l’allure suivante :

Aller plus loin

Une fois lancé sur cette voie, des interrogations techniques, liées à des problématiques de programmation en PHP, par exemple, se posent, c’est légitime.

Le site de documentation technique est conçu pour répondre à ces questions. Concernant les plugins, vous pouvez poursuivre à cette adresse pour une première approche sur les points d’entrée de SPIP (ou « pipeline »).


Voir le squelette de cette page Site réalisé avec SPIP | Espace de traduction | Espace privé