La syntaxe des balises SPIP

Fonctionnement simplifié

Une balise SPIP se place généralement à l’intérieur d’une boucle (puisqu’il faut pouvoir récupérer un élément d’un article, d’une rubrique, etc.). Le nom de ces balises est généralement simple, et nous fournirons, pour chaque type de boucle, la liste complète des balises que l’on peut utiliser.

Une balise est toujours précédée du signe dièse (#).

Par exemple, affichons une liste de noms d’articles :

<BOUCLE_articles(ARTICLES){id_rubrique}>
     #TITRE<br>
</BOUCLE_articles>

Lorsque la boucle sera exécutée, la balise SPIP #TITRE sera à chaque fois remplacée par le titre de l’article en question :

Titre de l'article 1
Titre de l'article 2
...
Titre du dernier article

Rien de bien compliqué : on se contente d’indiquer à l’intérieur du code HTML le nom de l’élément désiré, et celui-ci est remplacé par le contenu tiré de la base de données.

Codes optionnels

Dans la pratique, un élément de contenu est souvent accompagné de code HTML qui ne doit s’afficher que si cet élément existe, faute de quoi la mise en page devient imprécise.

Par exemple : il existe une balise SPIP pour indiquer le surtitre d’un article. Or de nombreux articles n’ont pas de surtitre.

Complétons l’exemple précédent :

<BOUCLE_articles(ARTICLES){id_rubrique}>
     #SURTITRE<br>
     #TITRE<br>
</BOUCLE_articles>

qui, classiquement, nous donne une liste d’articles, avec désormais l’indication du titre et du surtitre de chaque article. Mais que se passe-t-il si l’article n’a pas de surtitre ? On obtient le code :
« <br> », c’est-à-dire une ligne blanche (un retour chariot).

Ce que nous devons faire : n’afficher le code « <br> » que si un surtitre existe pour l’article.

La syntaxe de la balise SPIP devient alors :

{{[}} texte optionnel avant {{(#BALISE)}} texte optionnel après {{]}}

La balise qui détermine l’option est placée entre parenthèses, et l’ensemble du texte conditionnel entre crochets. Le texte optionnel avant et le texte optionnel après ne s’affichent que s’il existe, dans la base de données, un élément correspondant à cette balise.

Notre exemple devient :

<BOUCLE_articles(ARTICLES){id_rubrique}>
     [(#SURTITRE)<br>]
     #TITRE<br>
</BOUCLE_articles>

On obtient alors le résultat recherché : s’il existe un surtitre pour cet article, il est affiché et suivi du <br> ; s’il n’existe pas de surtitre, même le
<br> est occulté.

-  attention : cet affichage conditionnel ne fonctionne pas avec les balises dynamiques (par exemple #URL_LOGOUT).

-  Depuis SPIP 4.0, il est possible d’employer des boucles dans les parties optionnelles avant ou après d’une balise. Elles doivent être entières dans une même partie.

Utilisations avancées

On peut imbriquer des balises étendues les unes dans les autres. Ainsi, si dans notre exemple on voulait n’afficher le logo de l’article que si le surtitre est défini, on pourrait écrire :

<BOUCLE_articles(ARTICLES){id_rubrique}>
     [[(#LOGO_ARTICLE)<br>](#SURTITRE)<br>]
</BOUCLE_articles>

Note:On ne peut jamais mettre une boucle dans le code optionnel d’une balise. Mais si on veut faire n’afficher une boucle qu’en fonction d’une certaine balise, on peut utiliser <INCLURE{...}> à l’intérieur d’un code optionnel.

Balises non ambiguës

Quand on imbrique des boucles les unes dans les autres, il peut arriver que deux boucles aient des balises homonymes.

Par exemple, dans le code suivant :

<BOUCLE_rubriques(RUBRIQUES){id_rubrique}>
     <BOUCLE_articles(ARTICLES){id_rubrique}>
         #TITRE
     </BOUCLE_articles>
</BOUCLE_rubriques>

la balise #TITRE désigne le titre d’un article. Ainsi, si on voulait afficher le titre de la rubrique à l’intérieur de la boucle _articles, on ne pourrait pas utiliser #TITRE.

On peut appeler une balise homonyme de l’une des boucles englobantes en explicitant le nom de la boucle à laquelle la balise appartient. Il faut alors spécifier le nom de la boucle entre le # et le nom de la balise.

On écrira alors la balise #BALISE de la boucle _boucle [1] de la façon suivante : #_boucle:BALISE. Par exemple :

<BOUCLE_rubriques(RUBRIQUES){id_rubrique}>
     <BOUCLE_articles(ARTICLES){id_rubrique}>
         #_rubriques:TITRE > #TITRE
     </BOUCLE_articles>
</BOUCLE_rubriques>

affichera le titre de la rubrique, puis le titre de l’article :
la balise #TITRE pour la boucle _rubriques devient #_rubriques:TITRE pour ne pas être confondue avec la balise #TITRE de la boucle _articles.

Filtrer les résultats

Il est fréquent de vouloir modifier un élément tiré de la base de données, soit pour obtenir un affichage différent (par exemple, afficher le titre entièrement en majuscules), ou pour récupérer une valeur découlant de cet élément (par exemple, afficher le jour de la semaine correspondant à une date).

Dans SPIP, on peut directement appliquer des filtres aux éléments récupérés de la base de données, en les indiquant dans la syntaxe des balises SPIP, qui devient :

[ option avant (#BALISE|filtre1|filtre2|...|filtreN ) option après ]

La syntaxe est donc de faire suivre le nom de la balise, entre les parenthèses, par les filtres successifs, séparés par une barre verticale (nommée habituellement pipe).

-  attention : l’application de filtres ne fonctionne pas sur les balises dynamiques.

Voici quelques filtres fournis par SPIP :

-  majuscules, passe le texte en majuscules (plus puissant que la fonction de PHP correspondante, qui ne fonctionne pas correctement avec les caractères accentués) ; par exemple :

[(#TITRE|majuscules)]

La présente documentation consacre un article aux différents filtres livrés avec SPIP.

Court-circuiter le traitement par SPIP

SPIP applique un traitement typographique à tous les textes tirés de la base de données. En particulier, il place des espaces insécables avant certains symboles (point-virgule, point d’interrogation, etc.), et analyse des raccourcis de mise en page.

Dans certains cas, vous pouvez avoir besoin de court-circuiter ce traitement, afin de récupérer directement le texte brut tel qu’il est placé dans la base de données. Pour cela, il suffit d’ajouter une astérisque (*) à la suite de la balise SPIP. Ce qui donne :

[ option avant (#BALISE*|filtre1|filtre2|...|filtreN) option après]

(voir #BALISE* et #BALISE**)

Les paramètres des balises

Certaines balises [2] acceptent des paramètres. On passera alors une liste de paramètres entre accolade « { » et « } » avec des virgules « , » pour séparer chaque paramètre. Par exemple : #ENV{lang,fr}.

Un paramètre peut être une constante ou une autre balise. Seulement les balises de forme simple peuvent être passées en paramètres (i.e. pas de code optionnel ou de filtres). On peut mettre les paramètres entre guillemets simples « '...' » si l’on ne veut pas qu’ils soient interprétés par SPIP.