Plugin.xml

Proposition de documentation concernant la rédaction et le format du fichier plugin.xml des plugins pour spip (introduit dans SPIP 1.9.), en complément de Réaliser un premier plugin, Les Plugins, plugin_template/plugin.xml (accessoirement http://doc.spip.org/@Tuto-Se-servir... /SPIP-Zone,1803).

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='' />


<bouton id='mon_bouton_1' parent=>
       <icone>images/xml-valid-24.png</icone>
       <titre>Valider le site</titre>
       <url>w3c_go_home</url> <!-- nom de l'exec, facultatif, par defaut prend l'id -->
       <args>type=resume&id=1</args>
   </bouton>


</plugin>

L’ordre des éléments xml n’a pas d’importance.

Précision sur <description>

Cette partie est réservée à une description (assez courte) du plugin. Tu peux mettre tout ce que tu veux ici, à la seule condition de respecter les normes XML.

Pour assurer un maximum de compatibilité, il est parfois nécessaire de passer par les codes Unicode. Les accents de la langue française par exemple et autres caractères particuliers seront d’autant mieux restitués sur d’autres plateformes que la vôtre. Le « é » pourra donc être codé : é.

Sous format XML, Il est très important de fermer toute balise ouverte. Pour documenter un modèle SPIP, il est donc impossible d’utiliser la syntaxe <ModeleXX> (qui est une balise ouvrante), ni même <code><ModeleXX></code> ! La meilleure solution est d’utiliser la table Unicode : <ModeleXX>. C’est un peu contraignant, mais on ne crée pas des plugins tous les jours !

Rappel : la façon de coder une balise unique (ouvrante et fermante à la fois) est la même qu’en HTML. Par exemple : <br />.

Quelques liens :
http://Array.org/fr/charts/PDF/U0080.pdf
http://www.commentcamarche.net/base...

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 changement dans SPIP 1.9.3 concernant <install> ?

Précisions 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

Cas d’un plugin ou de spip

Dans l’attribut version, écrivez les numéros de version, séparés par un point-virgule, et encadrés par des crochets ou des parenthèses. Mettre un crochet pour inclure, ou une parenthèse pour exclure, par exemple <necessite id='CFG' version='[1.0;1.1)' /> fait que le plugin requiert CFG version 1.0 minimum (comprise) et 1.1 maximum (exclue). 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 (dans cette hypothèse, on pourrrait ajouter <necessite id='spip' version='[1.9.;]' /> à tous les plugin.xml).

Cas d’une bibliothèque

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;

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

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.

Remarque 1 : 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).

Remarque 2 : _DIR_PLUGINS mène au répertoire des pluginS et _DIR_PLUGIN_PREFIXPLUGIN mène au répertoire du plugin préfixé PREFIXPLUGIN ou PrefixPlugin.

Remarque 3 : En spip 1.9.3, en raison du dispositif de chargement automatique des plugins, il est impératif d’utiliser _DIR_PLUGIN_PREFIXPLUGIN pour pointer une ressource.

Précisions sur <bouton>

Une nouveauté de SPIP 1.9.3 (http://trac.rezo.net/trac/spip/tick..., http://trac.rezo.net/trac/spip/chan..., http://trac.rezo.net/trac/spip/chan...).

« pour ajouter des boutons dans les menus de l’espace prive sans coder :
-  pour ajouter un bouton dans le bandeau principal

<bouton id='mon_bouton_1' parent=>
    <icone>images/xml-valid-24.png</icone>
    <titre>Valider le site</titre>
    <url>w3c_go_home</url> <!-- nom de l'exec, facultatif, par defaut prend l'id -->
    <args>type=resume&id=1</args>
</bouton>

-  pour ajouter un bouton dans le bandeau secondaire

<bouton id='mon_sous_bouton' parent='mon_bouton_1'>
    <icone>images/xml-valid-24.png</icone>
    <titre>Valider le site</titre>
    <url>w3c_go_home</url> <!-- nom de l'exec, facultatif, par defaut prend l'id -->
    <args>type=complet&id=1</args>
</bouton>

 » (adapté de http://trac.rezo.net/trac/spip/chan...)

Exemple dans http://trac.rezo.net/trac/spip-zone...

Les boutons de 1^er niveau existant et acceptable pour l’attribut parent sont :
-  accueil
-  naviguer
-  forum
-  auteurs
-  statistiques_visites
-  configuration
-  aide_index
-  visiter

Précision sur les repertoire d’un plugin

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/

Précision sur action/ et exec/

action

Les script contenus dans action/ serve à faire des traitements comme :
-  inserer des données dans une base de données
-  écrire un fichier
-  créer un repertoire
-  ...

En gros tout ce qui ne nécéssite pas un affichage d’information.

Les scripts sont de la forme action_plugin_fonction_dist() avec :
-  action : préfixe de fonction imposé
-  plugin : le nom du plugin utilisant l’action
-  fonction : un nom de fonction
-  dist : ceci n’est pas obligatoire mais offre la possibilité d’une surcharge

Le fichier associé sera action/plugin_fonction.php

exec

Dans ce repertoire se trouvent les script qui sont dédiés à l’affichage. Ces scripts en tant que tel ne font aucun traitement mais pourront faire appel a des actions.

Un exec de base contiendra la plupart du temps un ou des formulaires qui feront appel à des action/
On pourra aussi penser à utiliser la fonction [< code>recuperer_fond()->http://doc < code>[recuperer_fond()->http://doc .spip.org/@recuperer_fond] </code > pour exploiter les squelettes

Les scripts sont de la forme exec_plugin_fonction_dist() avec :
-  exec : préfixe de fonction imposé
-  plugin : le nom du plugin utilisant l’action
-  fonction : un nom de fonction
-  dist : ceci n’est pas obligatoire mais offre la possibilité d’une surcharge

Le fichier associé sera exec/plugin_fonction.php