Version 24 — Août 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...
- /SPIP-1-9-Les-Plugins
- http://trac.rezo.net/trac/spip-zone...
- /SPIP-Zone,1803
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 changement dans 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).
Pour savoir si une bibliothéque est correctement installée, vous pouvez utiliser la fonction find_in_path()
Exemple d’utilisation :
$cheminlib = find_in_path('lib/repertoirebibliotheque');
<!--
Lors de l'utilisation pour requérir une bibliothèque externe, la fonction <code>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>
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(_DIR_PLUGIN_PREFIXPLUGIN);
$version = $infos['version'];
Les versions étant comparées pour les dépendances (cf. élément necessite) avec la fonction version_compare, il est préférable d’utiliser des versions au format indiqué dans la doc de version_compare.
<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.
Remarque : Des underscores peuvent être utiliser dans le prefixe. Toutefois les fichiers de lang devront être sans.
Si le prefixe est pre_fix
, les fichiers de lang seront de la forme prefix_lg.php (avec lg l’abreviation de la langue).
On sort ici du cadre strictement du fichier plugin.xml (ceci sera à mettre dans un article propre)
La structure de base d’un plugin sera :
/.
/.prefix_options.php
/.prefix_fonctions.php
/formulaires/
/balises/
/fonds/
/base/
/exec/
/action/
/lang/
/public/
action/ | |
base/ | pour mettre le fichier d’installation |
exec/ | |
fonds/ | les squelletes (dont ceux pour cfg) |
lang/ | les traductions |
public/ | les déclaration de balises personnalisées |