But
Il arrive parfois avec spip d’avoir à faire des combinaisons complexes de balises et de textes qui vont se retrouver à plusieurs endroits dans le même squelette ou même dans différents squelettes.
Il existe déjà INCLURE qui permet de modulariser une partie d’un squelette dans un autre fichier. Pourtant, c’est parfois fastidieux de créer un fichier pour une simple ligne de balises, sans aucune boucle.
Cette contribution produit un nouveau jeux de balises. Ceci permet de déclarer dans un fichier une liste de raccourcis qui correspondent à un ensemble de balise et de les rappeler simplement dans un squelette.
Par exemple, si on utilise la contrib des balises #EXIF, on va souvent utiliser ces deux combinaisons de balises :
- [(#EXIF|EXIF,DateTimeOriginal|date_EXIF2spip|sinon{#DATE}|affdate)]
- [(#EXIF|EXIF,UserComment|substr{5}|sinon{#DESCRIPTIF})]
Cette contribution va nous permettre d’appeler ces combinaisons de la façon suivante :
- #POSE_DATE_EXIF
- #POSE_DESCRIPTION_EXIF
Installation
Pour installer la contrib, c’est très simple :
- décompresser l’archive dans le répertoire racine de votre site [1].
- configurer la contrib en modifiant les deux chemins définis dans plug_pose/config.php :
-$plug_pose_racine_site
défini le chemin absolu vers la racine de votre site [2],
-$plug_pose_dossier_alias
défini le répertoire dans lequel chercher les fichiers de définition des alias. - ajouter à la fin du fichier mes_fonctions.php3 la ligne :
include('./plug_pose/plug_pose.php')
Pour installer les alias :
- il faut placer les fichiers XML dans le répertoire que vous avez spécifié dans la configuration (ou un sous répertoire) [3].
- ensuite, il faut charger la page plug_pose/calculer_pose.php. Cette page va compiler les fichiers XML et imprimer les informations fournies par l’alias.
Génération de balises
Cette contribution transforme des fichiers XML avec les descriptions des nouvelles balises en un code compréhensible par SPIP. Tous les fichiers avec un nom du style alias___.xml se trouvant dans le répertoire défini dans le fichier de configuration et ses sous répertoires seront compilés à l’installation.
La structure d’un fichier de description basique est simple. Voici un exemple pour la balise #POSE_DATE_EXIF
citée plus haut :
<aliases version_fichier="1.0">
<alias nom="date_exif">
<poser>
<![CDATA[
[(#EXIF|EXIF,DateTimeOriginal|date_EXIF2spip|sinon{#DATE}|affdate)]
]]>
</poser>
</alias>
</aliases>
La première balise aliases déclare un nouvel ensemble de raccourcis. L’attribut version_fichier permet de vérifier la compatibilité entre la version de ce fichier et la version de la contribution [4].
On déclare un nouveau bloc avec la balise alias à qui on donne le nom de la balise (sans le #POSE_) avec l’attribut nom.
Le bloc à poser à la place de cette nouvelle balise doit être déclaré entre balise poser. [Attention]
Exemple d’utilisation
Si l’idée de simplifier l’écriture de vos balises compliquées ne vous suffisez pas.
Imaginez le cas de l’utilisation du filtre sinon deux fois de suite :
[(#DESCRIPTIF|sinon{[(#CHAPO|sinon{pas de résumé})]})]
Même le super nouveau compilateur de la version 1.8 ne permet pas de passer des balises étendues en paramètres.
Mais, grâce à cette contribution, on peut définir une nouvelle balise :
<aliases version_fichier="1.0">
<alias nom="sinon_chapo">
<poser>
<![CDATA[
[(#CHAPO|sinon{pas de résumé})]
]]>
</poser>
</alias>
</aliases>
que l’on pourra appeler de la façon suivante :
[(#DESCRIPTIF|sinon{#SINON_CHAPO})]
Paramètres
Pour permettre une plus grande généricité des nouvelles balises introduites, un système de paramétrage a été introduit.
On peut donc passer à une balise #POSE____ autant de paramètres que l’on veut : [(#POSE_DATE_EXIF{<li>,</li>})]
Evidemment, il faut dire à la balise que faire de ces paramètres. Les paramètres de la balise remplaceront les chaînes de forme @...@
dans le bloc à poser.
Par exemple :
...
<poser>
<![CDATA[
[@avant@(#EXIF|EXIF,DateTimeOriginal|date_EXIF2spip|sinon{#DATE}|affdate)@apres@]
]]>
</poser>
...
Ici, @avant@
sera remplacé par le premier paramètre et @apres@
par le deuxième.
L’ordre des paramètres est défini par l’ordre de leur première occurrence dans le bloc à poser.
On peut omettre des paramètres, seul ceux présents sont remplacés :
- [(#POSE_DATE_EXIF{,quelquechose})]
remplacera seulement le 2e paramètre @apres@
.
Les paramètres non présents sont tout simplement enlevés.
Défauts
Pour simplifier la vie à tout le monde et éviter d’avoir à passer des paramètres à chaque fois que l’on appelle une balise, on peut spécifier des paramètres par défaut :
<aliases>
...
<alias nom="date_exif">
...
<parametre nom="avant">
<valeur>
<![CDATA[
<li>
]]>
</valeur>
</parametre>
<parametre nom="apres">
<valeur>
<![CDATA[
</li>
]]>
</valeur>
</parametre>
...
</alias>
...
</aliases>
la balise parametre permet de définir une valeur par défaut pour chaque paramètre. La valeur doit être définie entre les balises valeur. [Attention]
Le paramètre remplacera la chaîne définie par l’attribut nom. L’ordre de déclaration des paramètres par défaut prévaut sur l’ordre d’apparition des paramètres dans le bloc à poser.
Vérification
On peut limiter la liberté que l’on a sur le passage de paramètres. Par exemple, vouloir que l’utilisateur de la balise ne passe en paramètre que des balises html, ou que des balises pouvant être incluses dans une liste.
<aliases>
...
<alias nom="date_exif">
...
<parametre nom="avant">
<valeur>
<![CDATA[
<li>
]]>
</valeur>
<verification>
<![CDATA[
/<li.*>/U
]]>
</verfication>
</parametre>
<parametre nom="apres">
<valeur>
<![CDATA[
</li>
]]>
</valeur>
<verification>
<![CDATA[
/<\/li>/
]]>
</verfication>
</parametre>
...
</alias>
...
</aliases>
La balise verification accepte une expression régulière au format perl [5] qui mettra une contraintes sur le paramètre en question. [Attention]
Évidemment, il faut que le paramètre par défaut soit aussi compatible avec cette contrainte.
Jeux
On pourrait vouloir définir plusieurs paramétrage par défaut. Par exemple un pour faire une liste, un pour faire un paragraphe, etc...
Il existe pour cela la possibilité de déclarer des jeux de paramètres par défaut différents pour une balise :
<aliases>
...
<alias nom="date_exif">
...
<jeu nom="liste">
<parametre nom="avant">
<valeur>
<![CDATA[
<li>
]]>
</valeur>
<verification>
<![CDATA[
/<li.*>/U
]]>
</verfication>
</parametre>
<parametre nom="apres">
<valeur>
<![CDATA[
</li>
]]>
</valeur>
<verification>
<![CDATA[
/<\/li>/
]]>
</verfication>
</parametre>
</jeu>
<jeu nom="paraph">
<parametre nom="avant">
<valeur>
<![CDATA[
<p>
]]>
</valeur>
<verification>
<![CDATA[
/<p.*>/U
]]>
</verfication>
</parametre>
<parametre nom="apres">
<valeur>
<![CDATA[
</p>
]]>
</valeur>
<verification>
<![CDATA[
/<\/p>/
]]>
</verfication>
</parametre>
</jeu>
...
</alias>
...
</aliases>
la balise jeu permet de déclarer dans un paramètre un ensemble de paramètres qui seront utilisés dans certaines conditions. Le nom du jeu est définie par l’attribut jeu.
Jeux globaux
Certain jeux pourraient être utiles à plusieurs balises. Par exemple, les paramètres par défaut pour une liste ont beaucoup de chance d’être les mêmes pour la plupart des balises.
Au lieu de déclarer le même jeu plusieurs fois dans différents alias, on peut déclarer des jeux globaux en dehors de balises alias (les jeux doivent alors se trouver entre balises jeux) et les appeler depuis un alias avec une balise jeu.
<aliases>
...
<alias nom="date_exif">
...
<jeu nom="liste"/>
</alias>
<jeux>
<jeu nom="liste">
<parametre nom="avant">
<valeur>
<![CDATA[
<li>
]]>
</valeur>
<verification>
<![CDATA[
/<li.*>/U
]]>
</verfication>
</parametre>
<parametre nom="apres">
<valeur>
<![CDATA[
</li>
]]>
</valeur>
<verification>
<![CDATA[
/<\/li>/
]]>
</verfication>
</parametre>
</jeu>
</jeux>
</aliases>
Les jeux sont appelé en passant un paramètre spécial à la balise :
[(#POSE_DATE_EXIF{liste;})]
Pour choisir un jeu, il faut passé sont nom comme premier paramètre de la balise, séparé par un point virgule ( ;) de la liste normale des paramètres.
On peut ensuite spécifier des paramètres comme on l’aurait fait avant :
[(#POSE_DATE_EXIF{liste;<li class="maclasse">})]
On cherche d’abord un jeu dans l’ensemble des jeux locaux, puis dans les jeux globaux permis par cette balise.
Si aucun nom de jeu n’est spécifié, c’est le jeu par défaut qui est choisi. Le jeu par défaut est le premier déclaré dans l’alias, sauf s’il y a un attribut defaut qui spécifie un autre jeu dans la balise alias.
...
<alias nom="date_exif" defaut="paraph">
...
Nom de jeu dans l’url
Si le nom de jeu passé à la balise n’est pas déclaré comme valide dans un alias, le code cherche s’il n’existe pas une variable du même nom dans l’url spécifiant un nom de jeu valide.
Par exemple, si on écrit : [(#POSE_DATE_EXIF{var_jeu;})]
dans le squelette article.html. On pourra appeler la page avec une url :
article.php3 ?var_jeu=liste&id_article=12
Si le jeu spécifié dans l’url n’est pas valide (ou si aucun jeu n’est spécifié par l’url) alors le jeu par défaut est utilisé.
Contexte
Si on prend cet exemple de balise EXIF, il est évident qu’il n’y a pas d’intérêt à ce que celle ci soit utilisé dans une autre boucle qu’une boucle document.
On peut spécifier par l’attribut boucles de la balise alias quel sont les boucles dans lesquelles l’alias est valide. On peut donc spécifié une liste de noms de boucles valides séparés par des virgules (,).
...
<alias nom="date_exif" boucles="documents">
...
Cette fonctionnalité peut aussi être utilisée pour faire un affichage différent en fonction de la boucle où l’on se trouve (Comme avec les balises de base #TITRE qui retourner le titre d’un article si elle est dans une boucle articles et le titre d’une rubrique si elle est dans une boucle rubriques).
On peut donc spécifier plusieurs fois une balise alias avec le même nom à condition de mettre différent nom de boucles :
...
<alias nom="titre" boucles="articles">
....
</alias>
<alias nom="titre" boucles="rubriques,breves">
....
</alias>
...
Pour chaque définition on pourra donc avoir :
- un bloc à poser different,
- un jeu par défaut different,
- un ensemble de jeux different.
Documentation
Pour la plupart des balises : aliases, alias, jeu et parametre on peut utiliser l’attribut description pour ajouter une petite explication sur cet élément. Cette déscription sera affichée à l’installation des alias.
De plus, la balise aliases accepte un attribut doc qui doit être une URL vers une page de documentation des alias fournis (par exemple une page de contrib).
Récursions
Si on fait un #PSEUDO A qui appelle un #PSEUDO B et que le raccourcis B appelle le raccourcis A, ce que l’on appelle une récursion infinie va se passer : le système ne saura pas quand s’arrêter de remplacer les #PSEUDO.
La même chose peut se produire entre deux paramètres. On peut référencer un paramètre depuis un autre. Ainsi, si @param1@
vaut : blabla @param2@
et @param2@
vaut : @param1@ blibli
. On court à la catastrophe.
Il faut donc bien faire attention à ce que l’on fait, mais ce genre de récursions peut tout de même bénéfique dans certain cas.
Comment ça marche ?
Le fichier calculer_pose.php parse le fichier XML pour generer des fonctions php balise_POSE___()
que SPIP appelle quand il rencontre la balise en question.
Le code de ces fonctions spécifie les differents jeux et bloc de texte à poser pour cette balise. On appelle ensuite la fonction pose_calcul définie dans le fichier inc_alias.php.
Cette fonction choisie le bon jeu de paramétre et remplace les chaînes @...@
par les paramètres. Ensuite, en appelant les fonctions parser_champs_etendus et calculer_liste on fait appel aux fonctions du noyau SPIP qui calculent le code générant le contenu des balises.
Version de développement
Cette contrib est gérée sur spip-zone, on peut récupérer la dernière version de développement grâce à :
svn checkout svn://zone.spip.org/spip-zone/_contrib_/_balises_/alias/
Toutes contributions, comme par exemple une « librairie » de raccourcis ou des exemples d’utilisation de cette contrib sont les bienvenues sur cet espace colaboratif.
Aucune discussion
Ajouter un commentaire
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Suivre les commentaires : |