Une balise pour des blocs SPIP génériques et réutilisables

Ceci est une ARCHIVE, peut-être périmée. Vérifiez bien les compatibilités !

A l’instar du INCLURE pour recycler les boucles, voici une balise qui permet de faire des raccourcis vers des combinaisons complexes de balises SPIP.
Avec un système de paramétrage des balises, ce plugin permet l’écriture de blocs de contenus génériques.

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

dossier d’installation

Pour installer la contrib, c’est très simple :

  1. décompresser l’archive dans le répertoire racine de votre site [1].
  2. 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.
  3. ajouter à la fin du fichier mes_fonctions.php3 la ligne :
    include('./plug_pose/plug_pose.php')

Pour installer les alias :

  1. il faut placer les fichiers XML dans le répertoire que vous avez spécifié dans la configuration (ou un sous répertoire) [3].
  2. 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>

Choix du jeu

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.

Notes

[1le répertoire plug_pose peut être installé où l’on veut.

[2Attention, ici on parle du chemin physique et non de l’URL du site.

[3Il y a déjà 3 fichiers d’exemple fournis avec l’archive.

[4on sait jamais, elle pourrait évoluer.

[Attentionsi on veut placer du code html dans le bloc, il faut absolument l’entourer de :<![CDATA[ et ]]>

[5avec ses paramètres

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

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.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom