Cada tipus d’etiqueta permet seleccionar els elements de la base de dades d’SPIP: els articles, les seccions, les breus, etc. Cadascun d’aquests elements està a la vegada constituït d’elements precisos: un títol, una data, un text, etc. A l’interior d’un bucle, és necessari que hi puguem indicar en quin lloc del codi HTML es posen cadascun d’aquests elements concrets.
Per això, farem servir les etiquetes SPIP.
Funcionament simplificat
Una etiqueta SPIP es col·loca a l’interior d’un bucle (s’ha de saber si es vol recuperar un element d’un article, d’una secció, etc.). El nom d’aquestes etiquetes és generalment molt simple, i es proporcionarà per cada tipus de bucle, la llista completa de les etiquetes que es poden utilitzar.
Una etiqueta va sempre precedida pel signe de sostingut o coixinet (#).
Per exemple, mostrem una llista de noms d’articles:
<BOUCLE_articles(ARTICLES){id_rubrique}>
#TITRE<br />
</BOUCLE_articles>
Quan el bucle s’executi, l’etiqueta SPIP #TITRE serà cada vegada substituïda pel títol de l’article en qüestió:
Títol de l'article 1<br /> Títol de l'article 2<br /> ... Títol del darrer article<br />
Res que sigui molt complicat: ens acontentem en indicar a l’interior del codi HTML el nom de l’element desitjat, i aquest és substituït pel contingut extret de la base de dades.
Codis opcionals
A la pràctica, un element de contingut va sovint acompanyat de codi HTML, que només es mostra si aquest element existeix, sense el qual la compaginació esdevindria imprecisa.
Per exemple : existeix una etiqueta SPIP per indicar l’avantítol d’un article. No obstant, la majoria d’articles no en tenen.
Completem l’exemple precedent:
<BOUCLE_articles(ARTICLES){id_rubrique}>
#SURTITRE<br />
#TITRE<br />
</BOUCLE_articles>
que, clàssicament, ens dóna una llista d’articles, ara amb la indicació del títol i del subtítol de cada article. Però, què passa si l’article no té avantítol? S’obté el codi: «<br />», és a dir una línia en blanc (un retorn de carro).
El que hem de fer: mostrar el codi «<br />» només quan l’article té un avantítol.
La sintaxis de l’etiqueta SPIP és llavors:
[ text opcional abans (#BALISE) text opcional desprès ]
L’etiqueta que determina la opció està situada entre parèntesi, i el conjunt del text condicional entre claudàtors. El text opcional abans i el text opcional desprès només es mostren si existeix, a la base de dades, un element que correspongui a aquesta etiqueta.
El nostre exemple esdevé:
<BOUCLE_articles(ARTICLES){id_rubrique}>
[(#SURTITRE)<br />]
#TITRE<br />
</BOUCLE_articles>
Obtenim llavors el resultat buscat: si existeix un avantítol per aquest article, es mostra seguit de <br />; en canvi, si no existeix avantítol, també el <br /> queda ocult.
- atenció: aquesta visutalització condicional només funciona amb les etiquetes dinàmiques (per exemple #URL_LOGOUT).
Utilitzacions avançades
A partir d’[SPIP 1.8] es pot imbricar les etiquetes extenses unes dins les altres. D’aquesta manera, si en el nostre exemple volguéssim mostrar el logotip només si l’avantítol està definit, podríem escriure:
<BOUCLE_articles(ARTICLES){id_rubrique}>
[[(#LOGO_ARTICLE)<br />](#SURTITRE)<br />]
</BOUCLE_articles>
Nota: No podem posar mai un bucle dins el codi opcional d’una etiqueta. Però si només volem mostrar un bucle en funció d’una certa etiqueta, podem fer servir <INCLURE{...}> a l’interior d’un codi opcional.
Etiquetes clares
Quan s’imbriquen bucles els uns dins dels altres, ens podem trobar que dos d’ells tinguin etiquetes homònimes.
Per exemple, en el següent codi:
<BOUCLE_rubriques(RUBRIQUES){id_rubrique}>
<BOUCLE_articles(ARTICLES){id_rubrique}>
#TITRE
</BOUCLE_articles>
</BOUCLE_rubriques>
l’etiqueta #TITRE designa el títol d’un article. D’aquesta manera, si volíem mostrar el títol de la secció a l’interior del bucle _article, no podríem fer servir #TITRE.
A partir d’[SPIP 1.8], podem cridar una etiqueta homònima d’una dels bucles englobants explicitant el nom del bucle al que pertany l’etiqueta. En aquest cas fa falta especificar el nom del bucle entre el # i el nom de l’etiqueta.
Aleshores escriurem l’etiqueta #BALISE del bucle _boucle [1] de la següent manera: #_boucle:BALISE. Per exemple:
<BOUCLE_rubriques(RUBRIQUES){id_rubrique}>
<BOUCLE_articles(ARTICLES){id_rubrique}>
#_rubriques:TITRE > #TITRE
</BOUCLE_articles>
</BOUCLE_rubriques>
mostrarà el títol de la secció (rubrique) i, després, el títol de l’article: l’etiqueta #TITRE pel bucle _rubriques esdevé #_rubriques:TITRE per no ser confós amb l’etiqueta #TITRE del bucle _articles.
Filtrar els resultats
És freqüent que es vulgui modificar un element de la base de dades, ja sigui per obtenir una visualització diferent (per exemple, mostrar el títol completament en majúscules), o per recuperar un valor resultant d’aquest element (per exemple, mostrar el dia de la setmana corresponent a una data).
En l’SPIP, es poden aplicar directament filtres als elements recuperats de la base de dades, indicant-ho a la sintaxi de les etiquetes SPIP, que esdevé:
[ opció abans (#BALISE|filtre1|filtre2|...|filtren) opció desprès ]
La sintaxi és, doncs, posar entre parèntesi el nom de l’etiqueta seguida dels diferents filtres separats per una barra vertical (anomenada habitualment pipe).
Heus aquí alguns filtres dels que venen amb l’SPIP:
- majuscules (majúscules), passa el text a majúscules (aquest filtre és més potent que la funció PHP corresponent, que no funciona correctament amb els caràcters accentuats); per exemple:
[(#TITRE|majuscules)]
- justifier (justificar), mostra el text justificat a dreta i esquerre (és a dir <P align=justify>); per exemple:
[(#TEXTE|justifier)]
La present documentació dedica un article als diferents filtres que venen amb l’SPIP.
Saltar-se les transformacions de l’SPIP
SPIP aplica un tractament tipogràfic a tots els textos extrets de la base de dades. En particular, col·loca espais ineludibles abans de certs símbols (punt i coma, interrogació, etc.), i analitza les dreceres de compaginació.
En alguns casos, podeu tenir necessitat de saltar-vos aquest tractament, amb la finalitat de recuperar directament el text tal i com es trobava a la base de dades. Per això, en tindrem prou en afegir un asterisc (*) a continuació de l’etiqueta SPIP. Llavors tindrem:
[ opció abans (#BALISE*|filtre1|filtre2|...|filtren) opció desprès ]
(veure #BALISE* i #BALISE**)
Els paràmetres de les etiquetes
A partir d’[SPIP 1.8], algunes etiquetes [2] accepten paràmetres. Podrem passar una llista de paràmetres entre claus «{» i «}» amb comes «,» per separar cada paràmetre. Per exemple: #ENV{lang,fr}.
Un paràmetre pot ser una constant o una altra etiqueta. Només les etiquetes simples es poden passar com a paràmetres (i.e. ni codi opcional o filtres). Es poden posar els paràmetres entre cometes simples «'...'» si no es vol que siguin interpretades per SPIP.