Carnet Wiki

Plugin.xml

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..

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/paq...

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>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.

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.

note : quelles sont les nouveauté et chagemeent avec SPIP 1.9.3 concernant <install> ?

Précision sur <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) :

  • une version d’un plugin <necessite id='CFG' version='[1.0;1.1)' />
  • une version spip <necessite id='spip' version='[1.9207;]' />
  • une bibliothéque à télécharger depuis le net

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;

Précision sur <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'];

Précision sur <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.