Rédaction du paquet.xml

Cet article décrit les spécifications exhaustives du contenu du fichier paquet.xml qui, à partir de SPIP 3, remplace progressivement le fichier plugin.xml. Ce nouveau fichier XML doit être valide pour permettre l’activation du plugin sous SPIP.

Vous pouvez tester sa conformité sur la page Valider un paquet.xml

paqxmlgen/La description d’un plugin : paquet.xml

La description d’un plugin : paquet.xml

 Un nouveau standard de description

Un plugin SPIP nécessite d’être décrit pour être mis en œuvre avec fiabilité et activé par l’interface privée de SPIP. Jusqu’à présent, cette description était donnée pour chaque plugin par un fichier nommé plugin.xml.

À partir de la version SPIP 3.0, plugin.xml est remplacé par un fichier paquet.xml, plus simple dans son expression et conforme à la norme XML. Ce nouveau fichier facilite :

  • la lecture, en proposant un XML plus lisible et moins verbeux
  • la traduction, en déplaçant les descriptions dans les fichiers de langues
  • l’affichage des informations, en réduisant le texte au profit de données plus précises
  • l’écriture, en éliminant toute redondance dans les précisions de compatibilité
  • la mise au point, en soumettant le fichier au validateur XML avant d’autoriser l’activation du plugin.

 Structure générale de paquet.xml

Le fichier paquet.xml contient une balise englobante <paquet> unique précisant dans ses attributs l’ensemble des informations ne devant pas être répétées (comme la catégorie, le préfixe, la version...)

Cette balise unique contient des sous-balises réparties en 5 groupes qui doivent se succéder dans cet ordre :

  • le nom du plugin (complété par le slogan et la description qui ne sont plus des balises mais des items de langue retrouvés automatiquement) ;
  • les balises liées aux crédits et copyright du plugin, à savoir, <auteur>, <credit>, <copyright> et <licence> ;
  • la balise liée à la mise en traduction des modules de langue du plugin sous Salvatore, <traduire> ;
  • les balises techniques déclarant les pipelines, menus, onglets, dépendances entre plugins, etc ;
  • et éventuellement la ou les balises <spip> qui ne peuvent contenir que des balises techniques et qui sert à définir des alternatives par intervalle de compatibilité.

En outre, peuvent figurer après ces quatre groupes, des sous-balises <spip> destinées à décrire des mises en œuvre techniques différentes pour des versions de SPIP données. Cette balise qui joue quelque peu le même rôle que <paquet> ne contient a contrario que des balises dites techniques.

paqxmlpaquet/La balise <paquet>

La balise <paquet>

Contrairement à la balise <plugin> de plugin.xml, la balise englobante <paquet> est unique.

Elle possède quatre attributs obligatoires :


 prefix

Le préfixe est l’identifiant unique du plugin. C’est une chaine de caractères autorisant les lettres minuscules ou majuscules, les chiffres et le tiret bas.
Attention  : la longueur de cette chaîne est limitée à 30 caractères jusqu’à SPIP 4, et à 48 caractères ensuite.
Pour les thèmes, il est conseillé d’utiliser un nommage du type theme_nom_du_theme


 categorie

La catégorie permet de classifier les plugins par famille et de faciliter les recherches. Il existe 13 catégories prédéfinies :

ValeurLibellé en français
auteur Authentification, auteur, autorisation
communication Communication, interactivité, messagerie
date Agendas, calendrier, date
divers Objets nouveaux, services externes
edition Édition, impression, rédaction
maintenance Configuration, maintenance
multimedia Images, galerie, multimédia
navigation Navigation, organisation, recherche
outil Outil de développement
performance Optimisation, performance, sécurité
squelette Squelette
statistique Référencement, statistique
theme Thème

Il est à noter que les noms des catégories sont tous au singulier !


 version

Cet attribut désigne la version courante du plugin sous la forme x.y.z.

Il est important de normaliser le numéro de version d’un plugin et ses mécanismes d’évolution afin de déterminer facilement si une mise à jour existe. C’est pourquoi il est recommandé :

  • de systématiquement utiliser trois nombres entiers séparés par un point, x.y.z
  • d’initialiser la valeur à 0.1.0
  • d’éviter les suffixes dev, rc, alpha qui sont redondants avec l’état du plugin
  • d’incrémenter régulièrement la version en considérant les principes suivants,
    • un changement de x signale une incompatibilité,
    • un changement de y signale un ajout de fonctionnalité,
    • un changement de z signale des corrections de bugs.


 etat

Cet attribut complète la version du plugin en précisant l’état de développement courant de celui-ci. Il existe 4 états prédéfinis :

ValeurExplication
stable la version est publiée, documentée et supportée
test le plugin est en cours de tests avant publication finale (release candidate)
dev le plugin est en cours de développement et son utilisation n’est pas garantie (dev, alpha, beta)
experimental le plugin est une contribution expérimentale qui ne débouchera pas nécessairement sur un plugin utilisable

et sept attributs facultatifs :


 logo

Cet attribut indique le chemin vers le fichier image représentant le logo du plugin. Cet attribut était matérialisé par la balise <icon> dans plugin.xml.


 schema

Cet attribut indique la version courante du schéma de données utilisé par le plugin. Pour faciliter les mises à jour, il est conseillé de lui donner comme valeur :

  • un entier, comme le fait SPIP avec version_base, en prenant un numéro incrémental ou le numéro de dépot ;
  • ou un numéro de version conforme à la recommandation semver, soit x.y.z.

La date sous forme AAAAMMJJHHMM est à éviter.
Cet attribut était matérialisé par la balise <version_base> dans plugin.xml.

Si cet attribut est utilisé il est indispensable de créer un fichier prefixe_du_plugin_administrations pour définir les procédures d’installation, de mise à jour et de désinstallation du schéma de base de données du plugin.


 meta

Cet attribut indique la table que SPIP doit utiliser pour ranger les meta de configuration du plugin, à savoir :

  • la meta préfixe_du_plugin_base_version contenant la valeur de l’attribut “schema” du paquet.xml
  • les données de configuration spécifiques au plugin

Dans le cas où cet attribut est absent, la table spip_meta est utilisée par défaut.


 documentation, demonstration, developpement

Ces attributs sont les URL absolues (c’est à dire du type http://contrib.spip.net/Rainette-v2-une-version-multi-services) respectives de la documentation officielle du plugin, d’un site de démonstration et du lieu de développement du plugin.

Pour l’attribut demonstration uniquement, il est possible de fournir une URL relative du type demo/prefixe_plugin. Dans ce cas, un lien « démonstration » apparaitra dans la page d’administration des plugins pour se rendre dans la page de démo du plugin sur le site concerné.

Ces attributs remplacent la balise <lien> de plugin.xml avec l’avantage de pouvoir préciser la nature du lien.


 compatibilite

Cet attribut désigne l’intervalle de compatibilité maximal avec les versions de SPIP. À ce titre, si le plugin contient des mises en œuvre alternatives pour différents intervalles de compatibilité SPIP, cet attribut désigne l’union de ces intervalles.

L’intervalle utilise une écriture mathématique standard, dont les déclinaisons sont :

  • [v1 ;v2] qui correspond à v1 <= SPIP <= v2
  • [v1 ;[ qui correspond à SPIP >= v1
  • [ ;v2[ qui correspond à SPIP < v2
  • et toutes les autres combinaisons avec inclusion ou pas des bornes.

Cette information est essentielle pour éviter les erreurs d’activation de plugins. Aussi, il est fortement recommandé de définir la borne supérieure de cet intervalle, en particulier au moment où l’on crée une nouvelle branche de plugin.
En particulier, pour un paquet.xml d’un plugin compatible pour l’instant avec SPIP 3 il est conseillé d’écrire l’intervalle [3.0.0 ;3.0.*] : cela indique que le plugin est compatible avec toute la branche 3.0.

Cet attribut remplace la balise <necessite> de SPIP ou l’attribut “spip” de la balise <plugin> dans plugin.xml.

paqxmlnom/La balise <nom>

La balise <nom>

Cette balise obligatoire définit le nom du plugin. Il est recommandé :

  • de choisir un nom court et facilement compréhensible. Inutile de compléter le nom d’une phrase d’explication, cela étant maintenant dévolu au slogan du plugin.
  • de ne pas utiliser de chiffres, afin d’éviter toute confusion. En effet, tous les affichages des plugins sont aujourd’hui composés du nom et de la version pour identifier la branche concernée.

Cette balise, à l’instar de plugin.xml, peut être traduite , en particulier pour les plugins dont le nom est un terme générique (Facteur, Menus...). Mais la traduction se fait, comme pour le slogan et la description, dans le fichier de langue paquet-{préfixe_du_plugin}_{code_de_langue} et l’item se nomme préfixe_du_plugin_nom.

Traduction ou pas, il faut toujours insérer la traduction française dans la balise <nom> du paquet.xml.

paqxmldesc/Le slogan et la description

Le slogan et la description

Ces informations ne sont plus collectées dans une balise du fichier XML mais à partir d’items d’un module de langue spécifique au plugin et nommé paquet-{préfixe_du_plugin}_{code_de_langue}. Les items se nomment respectivement, préfixe_du_plugin_slogan et préfixe_du_plugin_description.
Ainsi, ces informations intègrent le processus SPIP standard de demande de traduction.

Il est fortement recommandé de remplir précisément ces informations :

  • le slogan, une phrase courte qui résume l’objet du plugin et qui sera toujours affichée en complément du nom
  • la description, qui ne doit pas se substituer à la documentation officielle mais doit fournir simplement le panel des fonctions voire des évolutions du plugin. Les liens vers une page de l’espace privé sont à proscrire.

paqxmlaut/La balise <auteur>

La balise <auteur>

Cette balise n’est ni obligatoire ni limitée en nombre. Elle est composée de deux attributs facultatifs :

  • lien, qui donne une URL décrivant l’auteur (ce peut être sa page sur SPIP Contrib)
  • mail, celui de l’auteur,

et d’un texte qui se limite au nom ou pseudo de l’auteur sans autres fioritures. Pour les crédits utiliser la balise <credit>.

paqxmlcred/La balise <credit>

La balise <credit>

Cette balise n’est ni obligatoire ni limitée en nombre. Destinée uniquement aux crédits - et pas aux auteurs - elle est composée d’un attribut facultatif :

  • lien, qui donne l’URL d’un site en relation avec le crédité,

et d’un texte qui se limite au nom du crédité sans autres fioritures.

paqxmllic/La balise <licence>

La balise <licence>

Cette balise n’est ni obligatoire ni limitée en nombre. Elle est composée d’un attribut facultatif :

  • lien, qui donne l’URL de la documentation officielle de cette licence,

et d’un texte qui se limite à son nom précis : GNU/GPL, LGPL, GPLv3...

paqxmlcopy/La balise <copyright>

La balise <copyright>

Cette balise n’est ni obligatoire ni limitée en nombre. Elle est composée uniquement d’un texte qui se limite à l’énoncé du copyright sans utilisation du caractère © qui sera rajouté dans les affichages appropriés.

paqxmltrad/La balise <traduire>

La balise <traduire>

Cette balise a pour but de lister les modules de langue d’un plugin qui doit être traduit en utilisant un gestionnaire de traduction comme Salvatore. Si le module est traduit “manuellement” , cette balise ne doit pas être utilisée.

Cette balise est composée uniquement de deux attributs obligatoires :

  • module, le nom du module de langue (à ne pas confondre avec le préfixe du plugin).
  • reference, le code de la langue de référence à partir de laquelle sont faites les traductions

et d’un attribut facultatif :

  • gestionnaire, précisant l’outil de traduction. La seule valeur admise actuellement est “salvatore”.

Note : le fichier normalisé lang/paquet-prefixe_langue.php contenant le slogan et la description du plugin n’a pas besoin d’être défini avec la balise <traduire>.

paqxmlbout/Les balises <menu> et <onglet>

Les balises <menu> et <onglet>

Ces balises ne sont ni obligatoires ni limitées en nombre. Elles permettent de créer des entrées dans le menu principal de l’espace privé ou des onglets dans certaines pages. Ces balises possèdent une même liste d’attributs, dont deux sont obligatoires :

  • nom, l’identifiant du menu ou de l’onglet
  • titre, le titre affiché sous la forme d’un item de langue module :item_du_titre

et quatre sont facultatifs :

  • parent, l’identifiant du menu principal auquel est rattaché l’entrée de menu ou un nom de regroupement de l’onglet concerné. Si absent ???
  • position, valeur indiquant la position absolue dans la liste des onglets ou des entrées de menu. La première position est 0 (zéro). Si cet attribut est absent l’onglet ou le menu est positionné en dernier. Il est recommandé d’éviter d’utiliser cet attribut plutôt réservé au core.
  • icone, le chemin relatif de l’icône à partir du dossier de base du thème en cours d’utilisation dans l’espace privé,
  • action, le nom de la page de destination (?exec=action). Si absent, c’est le nom du menu ou de l’onglet qui est utilisé,
  • paramètres, des paramètres éventuels de l’url de la page de destination sous la forme arg1=valeur1&arg2=valeur2

Le tableau suivant précise le nom de chacun des menus de l’espace privé de SPIP :

Nom Libellé en français
menu_accueil Accueil
menu_edition Édition
menu_publication Publication
menu_activite Activité
menu_squelette Squelettes
menu_administration Maintenance
menu_configuration Configuration
outils_collaboratifs Pas de libellé
outils_rapides Pas de libellé

paqxmlpipe/La balise <pipeline>

La balise <pipeline>

La balise pipeline permet de déclarer l’utilisation d’un pipeline existant ou de déclarer un nouveau pipeline. Elle est composée uniquement d’attributs, dont un seul est obligatoire :

  • nom, indiquant le nom exact du pipeline

et deux sont facultatifs :

  • inclure, le chemin du fichier PHP contenant la fonction pipeline sous la forme habituelle utilisée par SPIP, dossier/nom_fichier. Cet attribut est omis lorsque l’on déclare un nouveau pipeline.
  • action, le nom de la fonction activée par le pipeline et présente dans le fichier désigné par l’attribut inclure. Si action n’est pas précisée, la fonction utilisée sera celle nommée prefixe_nom_pipeline.

paqxmlnec/Les balises <necessite> et <utilise>

Les balises <necessite> et <utilise>

Ces balises permettent d’établir des dépendances entre plugins : <necessite> exprime une dépendance forte, le plugin ne pouvant être activé sans le plugin nécessité, alors que <utilise> exprime uniquement une dépendance faible, le plugin pouvant être activé sans le plugin utilisé. La balise <utilise> a un impact en matière de priorité : si le plugin A utilise le plugin B, les fichiers de A seront prioritaires sur ceux de B [1] et A passera après B dans les pipelines [2]. Ces balises sont composées uniquement d’attributs, dont un seul est obligatoire :

  • nom, identifiant de façon unique le plugin par son préfixe

et un facultatif :

  • compatibilite, qui représente l’intervalle de compatibilité de la dépendance. L’absence de version désigne une compatibilité toute version.

paqxmllib/La balise <lib>

La balise <lib>

Cette balise permet d’établir une dépendance forte avec une librairie de services (jQueryUI, Fancybox...). Elle est particulièrement utile pour éviter d’accumuler les mêmes librairies dans plusieurs plugins SPIP. Cette balise est composée de deux attributs obligatoires :

  • nom, identifiant unique la librairie (permet de spécifier le nom du dossier décompressé de l’archive),
  • lien, qui représente l’URL de l’archive de la librairie ; si ce lien est fonctionnel, cette archive sera téléchargée automatiquement par SPIP lors de l’activation du plugin.

paqxmlproc/La balise <procure>

La balise <procure>

Cette balise exprime le fait qu’un plugin fournit un service donné, qui aujourd’hui coïncide avec le plugin lui-même. Cette balise n’est encore utilisée que par le noyau de SPIP.

Elle possède les même attributs que la balise <necessite>.

paqxmlpath/La balise <chemin>

La balise <chemin>

La balise <chemin> et son attribut path permettent de déclarer dans le path de SPIP les dossiers du plugin accessibles automatiquement. Si aucun chemin n’est précisé, seuls les dossiers habituels du path sont accessibles (c’est le cas classique).

La balise <chemin> est composée d’un attribut obligatoire :

  • path, le dossier que l’on veut rendre accessible

et d’un attribut facultatif :

  • type, définissant la portée de l’accessibilité pouvant prendre les valeurs “public” (accessible uniquement dans l’espace public), “prive” (accessible uniquement dans l’espace privé). Si absent, l’accessibilité est totale (privé + public).

Si un chemin spécifique est déclaré, la règle par défaut de SPIP est annulée et il faut donc la déclarer explicitement par une deuxième balise <chemin> si vous en avez aussi besoin :

Note : cette balise ne sera peut-être pas maintenue.

paqxmlscript/Les balises <script> et <style>

Les balises <script> et <style>

Les balises <script> et <style> disponibles depuis SPIP 3.1 permettent de déclarer l’inclusion systématique de scripts ou de feuilles de style dans le header. A cet égard, cette déclaration permet d’éviter d’écrire du code répétitif dans les pipelines insert_head_css et insert_head (et dans leur équivalent pour le privé).

Ces balises possèdent toutes les deux un attribut obligatoire :

  • source, le nom du fichier à inclure

et un attribut facultatif :

  • type, définissant la portée de l’inclusion pouvant prendre les valeurs “public” (inclus uniquement dans l’espace public), “prive” (inclus uniquement dans l’espace privé). Si absent, l’inclusion est faite dans les espaces privé et public.

La balise <style> possède un attribut complémentaire facultatif :

  • media, qui a la même signification que l’attribut homonyme de la balise HTML <link> et prend donc les mêmes valeurs. Si absent, l’inclusion est faite pour tous les media.

paqxmlgenie/La balise <genie>

La balise <genie>

La balise <genie> disponible depuis SPIP 3.1 permet de déclarer un CRON. A cet égard, cette déclaration permet d’éviter d’écrire du code répétitif dans le pipeline taches_generales_cron.

Cette balise possède deux attributs obligatoires :

  • nom, le nom du CRON
  • periode, nombre de secondes s’écoulant entre deux activation du CRON.

paqxmlspip/La balise <spip>

La balise <spip>

Cette balise a pour but de spécifier une mise en œuvre particulière du plugin pour un intervalle de compatibilité SPIP donné. À ce titre, la balise <spip> possède un attribut obligatoire : compatibilite , qui joue exactement le même rôle que l’attribut homonyme de <paquet>, à ceci près qu’il identifie un sous-intervalle de compatibilité comparé à l’attribut de la balise <paquet>.

Cette balise <spip> ne peut contenir que les balises dites techniques, à savoir :

  • <menu>, <onglet>,
  • <pipeline>,
  • <necessite>, <lib>, <utilise> et <procure>,
  • <chemin>,
  • et depuis SPIP 3.1 <script>,<style>,<genie>.

En outre, il est recommandé de ne pas répéter des balises techniques déjà présentes dans la balise paquet car celles-ci ont pour rôle de définir les mises en œuvre communes quelle que soit la compatibilité SPIP. Ainsi, contrairement à plugin.xml, cette écriture élimine toute répétition d’informations : seules les balises techniques nécessaires apparaissant dans <spip>.

paqxmlfoi/Les fonctions, options et administrations

Les fonctions, options et administrations

Les balises <fonctions>, <options> et <install> de plugin.xml ne sont plus reprises dans la nouvelle DTD de paquet.xml.

Les fichiers correspondants sont maintenant uniques et normalisés : il doivent être placés à la racine du plugin et porter le nom :

  • prefixe_du_plugin_options.php pour les fonctions, variables et constantes nécessaires à l’espace privé ;
  • prefixe_du_plugin_fonctions.php pour celles nécessaires à l’espace public :
  • prefixe_du_plugin_administrations.php pour celles nécessaires aux mise en œuvre, mise à jour et mise au placard d’un plugin.

paqxmlexe/Exemples de paquet.xml

Exemples de paquet.xml

Exemple 1 : plugin farfelu utilisant toutes les balises sauf la balise <spip>

Exemple 2 : plugin utilisant la balise <spip>

Depuis la version SPIP 3.1, un menu « développement » à été rajouté à la barre du privé. Cet exemple montre comment on peut utiliser la balise <spip> pour changer l’entrée de Vertèbres du menu maintenance au menu développement à partir de SPIP 3.1.

[1Les squelettes de A pourront par exemple surcharger ceux de B.

[2Dès lors, deux plugins ne peuvent pas s’utiliser mutuellement, car cela provoquera une erreur dans le calcul des priorités.