Version 41 — Mai 2008 — 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.0), en complément de Réaliser un premier plugin, SPIP 1.9 - Les Plugins, plugin_template/plugin.xml (accessoirement http://doc.spip.org/@Tuto-Se-servir... et SPIP-Zone).
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 -->
<plugin>
<!-- Nom du plugin -->
<nom> NomPlugin </nom>
<!-- Auteur du plugin -->
<auteur> AuteurPlugin </auteur>
<version>0.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>
<!-- pour connaitre l'ensemble des pipeline voir
http://doc.spip.org/@Tuto-Se-servir-des-points-d-entree
http://trac.rezo.net/trac/spip/browser/spip/ecrire/inc_version.php#Tuto-Se-servir-des-points-d-entree -->
<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
branche 1.9.3 à 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>
<onglet id='mon_onglet_1' parent='configuration'>
<icone>images/img-24.png</icone>
<titre>Onglet dans configuration</titre>
<url>mon_onglet</url> <!-- nom de l'exec, facultatif, par defaut prend l'id -->
<args></args>
</onglet>
</plugin>L’ordre des éléments xml n’a pas d’importance.
<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 utiliser une balise dans cette zone (par exemple pour documenter un modèle rajouté par le plugin), il est donc impossible d’utiliser la syntaxe <balise> ! 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 />.
-* début de la liste officielle des caractères d’Array
<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;]' />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. (Si cette suggestion est accomplie, on pourrrait ajouter <necessite id='spip' version='[1.9.0;]' /> à tous les plugin.xml.)
Cas d’une bibliothèque
Une bibliothèque doit être un fichier .zip.
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');
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 (par exemple successivement 0.1, 0.2, 0.2.1, 0.2.2, 0.3, 1.0, 1.0.1).
<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.
<bouton> et <onglet> 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...
« le bandeau secondaire » correspond aux aux boutons liés à un bouton du bandeau principal, pas à la deuxième ligne (les boutons « Tout le site », « Navigation rapide », « Rechercher »... « Se déconnecter »). Les codes/identifants de boutons de premier niveau existants et acceptables pour l’attribut parent (d’un bouton de deuxième niveau) sont ceux du du bandeau principal (en haut de ?exec=) :
- accueil
- naviguer
- forum
- auteurs
- statistiques_visites
- configuration
- aide_index
- visiter
(on verra plus tard si il y a l’utilité d’autres emplacements dans l’interface privé)
(plus ceux ajoutéds auparavent par un plugin)
Le permier exemple ci-dessus fait créer un bouton dans le bandeau principal, avec sur le bouton « Valider le site » et l’image images/xml-valid-24.png, et renvoyant vers ?exec=w3c_go_home&type=complet&id=1.
Vous pouvez utiliser une structure similaire avec <onglet> pour ajouter un onglet à une page. Il faut que cette page puisse afficher les onglets, ceci est défini par l’utilisation dans la page de la fonction « barre_onglet » comme ici dans /exec/configuration.php : echo barre_onglets("configuration", "contenu");
Se referer maintenant à :
[->http://doc.spip.org/@plugin .
xml]
Le principe du mode wiki demeure, les informations techniques tel que ce document migrent maintenant sur doc.spip.org
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
./action/
./balises/
./base/
./exec/
./fonds/
./formulaires/
./lang/
./public/|action/ | pour effectuer des traitements |
|base/ | pour mettre le fichier d’installation |
|exec/ | pour gérer des affichages spécifique coté privé|
|fonds/ | les squelettes (dont ceux pour cfg) |
|lang/ | les traductions |
|public/ | les déclaration de balises personnalisées |
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 recuperer_fond() 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
Si vous placez les fichiers d’un squelette à la racine de votre plugin (par exemple dans plugins/mon_squelette/) et activez ce plugin (qui contient les attributs normaux d’un plugin, comme le fichier plugin.xml, etc) cela vous permet d’avoir un squelette embarqué dans un plugin.
N’oubliez pas que spip va choisir le fichier de squelette à charger en suivant l’ordre de priorité décroissante suivant :
squelettes/ > plugins/ > dist/ > ecrire/.
Par exemple, pour un fichier a.html, c’est /squelettes/a.html qui sera prioritaire sur plugins/mon_squelette/a.html. De la même façon, s’il y a les fichiers /plugins/mon_squelette/a.html, plugins/mon_squelette/b.html et squelettes/a.html, spip affichera squelettes/a.html et plugins/mon_squelette/b.html (le fichier squelettes/b.html n’existant pas)