Le terme de #BALISE (placé dans un squelette) identifie pour le moteur de SPIP un élément à calculer pour l’afficher au sein du squelette, en fonction du contexte de boucle et d’environnement courant.
Ne pas confondre avec les balises HTML, mots-clés du langage HTML de description des pages : les balises HTML sont elles mises entre < ..balise HTML..>
; les instructions SPIP en reprennent parfois la syntaxe en étendant le langage.
Ainsi les instructions SPIP utilisent cette syntaxe HTML (bien qu’elles doivent être ’compilées’ par SPIP pour être traitées [2] : celles décrivant les
Mais les balises #SPIP ne seront calculées (et traitées) que par un squelette SPIP,
sinon elles seront seulement affichées textuellement...
La syntaxe d’identification d’une balise est d’avoir un mot-clé en Majuscules, préfixé d’un dièse (#). La plupart des balises acceptent de recevoir des paramètres, mis entre accolades et non entre parenthèses comme dans les fonctions traditionnelles ; en effet, les parenthèses sont utilisées pour décider de l’affichage de parties optionnelles avant et après le texte généré par la balise, le tout étant délimité entre crochets..
Balises avec parties conditionnelles/optionnelles
Une balise SPIP permet d’afficher automatiquement le contenu d’un champ de la table parcourue par la boucle englobante ; si le champ est vide, rien n’est affiché.
Mais peut-être voudra-t-on afficher des compléments entourant la valeur d’un champ pris dans une occurrence de la base de données ? Mettre le nom de balise entre parenthèses va induire un test sur le contenu résultat, et s’il est vide/blanc, toute ce qui sera contenu dans la paire de crochets englobant sera également ’affiché a blanc : l’exemple type est est la balise #REM
qui se comporte comme [
non affiché
(
#REM
)
pas affiché non plus
]
.
Le compilateur de SPIP peut avoir à calculer une balise dans plusieurs contextes, ce qui sera l’occasion de s’intéresser à Balises, critères et filtres : à ne pas confondre...
Balise de champ dans une boucle
Dans un squelette la structure de base est la boucle de parcours d’une table de données ; le premier besoin est d’afficher (les valeurs) des champs de la table.
Il suffit d’indiquer le nom de champ selon la syntaxe indiquée, pour assurer l’affichage du champ de données correspondant [3].
SPIP vous permet de pré-traiter cet affichage avec un grand nombre de filtres, fonctions qui s’appliquent à l’argument reçu (donc introduit par le signe |
) qui seront le plus souvent des fonctions de formatage ou de mise en forme.
Balises calculées sur la base de données
L’accès à la base de données de SPIP est simplifié, car le moteur offre de nombreuses fonctionnalités sous forme abrégée ; ainsi une balise #LESAUTEURS
fournit à l’affichage la liste de tous les auteurs d’un article (car ils peuvent être plusieurs à co-rédiger dans l’espace privé).
Plus surement vous ferez appel à la balise INCLURE, et vous aurez besoin souvent des balises d’#URL_
fournissant immédiatement le calcul des hyper-liens vers les composants du site (Article, Rubrique, etc..) : un usage très fréquent donne un lien d’appel vers un article, dans une boucle de recherche des articles dans la rubrique : exemple :
<BOUCLE_rubriques(RUBRIQUES){racine}>
<h2 class="h2"><a href="#URL_RUBRIQUE">#TITRE</a></h2>
<ul class="liste-items"><!-- Articles de la rubrique -->
<BOUCLE_articles(ARTICLES){id_rubrique} {!par date} >
#INCLURE{fond=inclure/article-resume,id_article}
</BOUCLE_articles>
</ul>
</BOUCLE_rubriques>
N.B. : attention aux différences avec <INCLURE..
Balises de formulaires calculés
Toujours pour faciliter la gestion des squelettes, le moteur de SPIP étend le principe et la syntaxe des balises pour permettre d’#INCLURE
des noisettes comme ci-dessus, ou meme des FORMULAIRES prédéfinis, c’est la série des balises #FORMULAIRE_xxx
Programmation de Balises personnalisées
Ce mécanisme des balises peut très facilement être étendu, en particulier pour appeler une exécution spécifique de code php dans vos squelettes : ce sont les balises utilisateurs, que l’on associe à un appel de fonction php dans un squelette.
Vous pourrez trouver deux qualificatifs pour les balises de SPIP :
les balises statiques : gardent un code constant pour le cache du squelette,
les balises dynamiques : sont recalculées pour chaque occurrence de page [4]
La définition d’une balise personnalisée #TOTO
s’effectue en écrivant dans votre fichier mes_options une fonction php nommée :
- function balise_TOTO($p) {
- // code php de votre balise : voir ecrire/public/balises.php
- ....
- $p->code = .. ; // renvoyer le résultat à insérer dans l'affichage final
- return $p;
- }
N.B. Pour l’utilisation de paramètres contextuels du squelette, c’est un peu plus compliqué ;-)
Article publié le 14 janvier 2012, et actualisé en juin 2018 .
Répondre à cet article