Version 20 — Juillet 2007 — cam.lafit
Proposition de documentation concernant la rédaction et le format du fichier plugin.xml des plugins pour spip, introduit dans SPIP 1.9..
Voir aussi
- http://www.spip.net/fr_article3448.html
- http://doc.spip.org/@Tuto-Se-servir...
- http://www.spip-contrib.net/SPIP-1-...
- http://trac.rezo.net/trac/spip-zone...
- http://files.spip.org/spip-zone/paq...
L’écriture du plugin ne supporte pas les caractères accentués (sauf dans les commentaires), il faut donc leur substituer les codes HTML.
Comment lire :
<!-- Ceci est un commentaire -->
titi|toto : soit titi soit toto (ou exclusif)
<plugin>
<!-- Nom du plugin -->
<nom> NomPlugin </nom>
<!-- Auteur du plugin -->
<auteur> AuteurPlugin </auteur>
<version> .1 </version>
<etat>dev|test|stable|experimental</etat>
<icon></icon>
<description> Un descriptif autant complet que possible, utilisation de la syntaxe spip autorisée.</description>
<!-- URI de documentation -->
<lien> une url interne ou bien sur le net </lien>
<!-- précise le prefixe utilisé pour toutes les fonctions du plugin, en général le nom du plugin -->
<prefix>prefixplugin</prefix>
<!-- précise le fichier à charger à chaque recalcul, partie publique -->
<fonctions>chemin du fichier </fonctions>
<!-- précise le fichier à charger à chaque appel de la page, partie publique -->
<options>chemin du fichier </options>
<!-- Chemin du fichier d'installation et de mise à jour -->
<install>chemin du fichier</install>
<!--pipeline, surcharge de fonction à des moments précis de la génération d'une page spip -->
<pipeline>
<!-- voir la page sur doc.spip.org, pour connaitre l'ensemble des pipeline -->
<nom>point_entree</nom>
<!-- nom de la fonction a appelé sans son prefixe -->
<action>fonction</action>
<!-- chemin du fichier contenant la fonction -->
<inclure>fichier.php</inclure>
</pipeline>
<!-- précise les dépendances vis-à-vis de d'autres plugins (ou de spip, voir plus bas)-->
<necessite id="nomplugin" version="[versionminimale;versionmax]" />
<!-- indique un zip externe nécessaire -->
<!-- à partir de spip svn 98xx -->
<!-- id indique le répertoire où est chargé le zip, /lib/nom -->
<necessite id="lib:nom" src="http://url-complete-du/fichier.zip" />
<!-- Indique si le plugin concerne tout le site ou seulement l'espace privé. A confirmer
<chemin dir="./"> public
<chemin dir="./ecrire/"> privé -->
<chemin dir='' />
</plugin>
L’ordre des éléments xml n’a pas d’importance.
<install>
Lors de la déclaration de la balise
nom du fichier qui doit être appelé.
Il y a un consensus :
- pour avoir ce fichier dans le répertoire base de ton plugin
- d’utiliser le prefixe déclaré dans
Ce qui donne
Après dans ce fichier. On déclare une fonction :
function prefixeplugin_install($action){
switch ($action){
case 'test':
//Contrôle du plugin à chaque chargement de la page d'administration
// doit retourner true si le plugin est proprement installé et à jour, false sinon
break;
case 'install':
//Appel de la fonction d'installation. Lors du clic sur l'icône depuis le panel.
//quand le plugin est activé et test retourne false
break;
case 'uninstall':
//Appel de la fonction de suppression
//quand l'utilisateur clickque sur "supprimer tout" (disponible si test retourne true)
break;
}
}
Donc ’test’ se lance à chaque fois qu’on accède à la page
d’administration des plugins. Cela peut donc servir lors des mises à
jours.
- ’install’ sert aux opérations lors de l’activation du plugin.
- ’uninstall’ sert aux opérations lors de la suppression du plugin.
Dans les exemples que j’ai pu voir test et install sont assez proches.
note : quelles sont les nouveauté et chagemeent avec SPIP 1.9.3 concernant <install>
?
<necessite>
Une nouveauté de SPIP 1.9.3.
<necessite>
sert pour 3 cas de figure (triés par ordre chronologique d’ajout dans le code de spip) :
<necessite id='CFG' version='[1.0;1.1)' />
<necessite id='spip' version='[1.9207;]' />
Dans l’attribut version, écrivez les numéros de version, séparés par un point-virgule, et encadrés par des crochets pour inclure et des parenthèses pour exclure. Voir http://trac.rezo.net/trac/spip/chan.... Sachez que les versions sont comparées avec la fonction version_compare.
Attention, pour la version de SPIP, il ne s’agit pas de la version affichée et connue, mais de $spip_version_code, qui se trouve dans le fichier ecrire/inc_version.php, par exemple « $spip_version_code = 1.9207 ». Cela est succeptible de changer (si ce n’était pas le cas, on pourrrait ajouter <necessite id='spip' version='[1.9.;]' />
à tous les plugin.xml).
Cas d’une bibliothéque
Lors de l’utilisation pour requérir une bibliotheque externe, la fonction find_lib()
permet de controler sa présence. La fonction retourne le chemin de la bibliothéque si celle ci existe autrement false.
Exemple d’utilisation :
$cheminlib = find_lib(nom)
ou $cheminlib = find_lib(nom/sousrepertoire)
if (!$cheminlib)
return $flux;
<version>
Lors d’une mise à jour, il est possible de récuperer la version depuis plugin.xml. Cela evite une écriture redondante de la version entre les fichiers php et xml.
Dans le code suivant, prefixplugin
est à remplacer par la valeur saisie dans la balise <prefix>
include_spip('inc/plugin');
//recupére les informations de plugin.xml
$infos = plugin_get_infos('prefixplugin');
$version = $infos['version'];
<prefix>
Lors de l’activation du plugin SPIP met en place des constantes globales. Parmi celle ci se trouve
_DIR_PLUGIN_PREFIXPLUGIN
qui indique le chemin du plugin depuis la racine.