Carnet Wiki

Plugin.xml

Version 15 — Juillet 2007 — 82.127.xx.xx

Proposition de documentation concernant la rédaction du plugin.xml

Référence

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/paquets.rss.log.txt]

Restrictions


L’écriture du plugin ne supporte pas les caractères accentués (sauf dans les commentaires), il faut donc leur substituer les codes HTML.

Structure initiale

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>unprefix</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 spip ou d'autres plugins -->
   <necessite id="nomplugin" version="[versionminimale;versionmax]" />


<!-- peut préciser aussi une version de spip -->
   <!-- les versions ne sont pas celle de svn ou ni vraimement la numérotation officielle -->
   <!-- les version à preciser sont dans /ecrire/inc_version.php ligne 307 à 313 avec qques explications -->
   <necessite id="SPIP" version="[versionminimale;versionmax]" />


<!-- indique un zip externe nécessaire -->
   <!-- à partir de spip svn 9783 -->
   <!-- id indique le répertoire où est chargé le zip,  /lib/nom -->
   <necessite id="lib:nom" src="http://url-complete-du/fichier.zip" />


<!-- à préciser -->
   <!-- Indique si le plugin concerne tout le site ou seulement l'espace privé. 
       <chemin dir="./"> public
       <chemin dir="./ecrire/"> privé -->
   <chemin dir='' />


</plugin>

Précision sur <install>

Lors de la déclaration de la balise , tu indiques juste le
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 prefixeplugin

Ce qui donne
base/prefixeplugin_upgrade.php

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.

Précision sur <necessite>

<necessite> sert pour 3 cas de figure :

  • une version spip
  • une version d’un plugin
  • une bibliothéque à télécharger depuis le net

Cas de la version de spip

<necessite id='SPIP' version='[1.9207;]' />

Le numéro de version se trouve dans le fichier ecrire\inc_version.php, par exemple : $spip_version_code = 1.9207.

Le numéro de version est construit de cette façon : 1.xxyy : xx00 versions stables publiees, xxyy versions de dev (ce qui marche pour yy ne marchera pas forcement sur une version plus ancienne) type nouvelles fonctionnalites, deplacement de fonctions.

Cas d’une bibliothéque

Pour les plugin et spip, c’est opérationnel depuis environ la version svn 9023. Dans l’attribut version utilisez des crochets pour inclure et des parenthèses pour exclure. Voir http://trac.rezo.net/trac/spip/chan....

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;