Chaque type de boucle permet de sélectionner des éléments de la base de données de SPIP : des articles, des rubriques, des brèves, etc. Chacun de ces éléments est lui-même constitué d’éléments précis : un titre, une date, un texte, etc. A l’intérieur d’une boucle, il faut donc pouvoir indiquer à quel endroit du code HTML on place tel ou tel de ces éléments précis.
Pour cela, on va utiliser des balises SPIP.
Fonctionnement simplifié
Une balise SPIP se place à l’intérieur d’une boucle (puisqu’il faut savoir si l’on veut 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}>
<LI> #TITRE
</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 :
<LI> Titre de l'article 1
<LI> Titre de l'article 2
...
<LI> 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}>
<LI> #SURTITRE<BR>
#TITRE
</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 :
« <LI> <BR>
», c’est-à-dire une petite puce suivie d’une ligne blanche.
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}>
<LI> [(#SURTITRE)<BR>]
#TITRE
</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é.
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 succesifs, séparés par une barre verticale (nommée habituellement pipe).
Remarque. En réalité, les filtres sont des fonctions PHP. Vous pouvez donc utiliser directement les fonctions de PHP (à condition que ces fonctions fonctionnent avec une seule variable), en plus des fonctions livrées avec SPIP.
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)]
justifier, affiche le texte en justification totale (c’est-à-dire <P align=justify>) ; par exemple :
[(#TEXTE|justifier)]
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 ]
Filtres à plusieurs variables
Attention, ce passage s’adresse aux utilisateurs avertis. [SPIP 1.5] autorise le passage de paramètres dans les filtres. La syntaxe est
La fonction filtre doit être définie de la manière suivante dans mes_fonctions.php3 :
Une telle fonction a donc forcément pour première variable le texte à traiter (ici, le texte de #BALISE).
