Cada tipo de bucle permite seleccionar los elementos de la base de datos de SPIP: artículos, secciones, breves, etc. Cada uno de estos elementos está a su vez compuesto por elementos precisos: un título, una fecha, un texto, etc. En el interior de un bucle, es necesario poder indicar en qué lugar del código HTML se ponen tal o cual de dichos elementos.
Para esto vamos a utilizar las balizas SPIP.
Funcionamiento simplificado
Una baliza SPIP se coloca en el interior de un bucle (pues hay que saber si se quiere recuperar un elemento de un articulo, una sección, etc.). El nombre de estas balizas es generalmente simple, y se proporcionará, para cada tipo de bucle, la lista completa de balizas que se pueden utilizar.
A una baliza siempre la precede el signo diesis (#).
Por ejemplo, mostremos una lista de títulos de artículos:
<BOUCLE_articulos(ARTICLES){id_rubrique}>
#TITRE
</BOUCLE_articulos>
Cuando el bucle se ejecute, la baliza SPIP #TITRE será remplazada cada vez por el título del artículo en cuestión:
Título del artículo 1
Título del artículo 2
...
Título del último artículo
No es muy complicado: nos contentamos con indicar en el interior del código HTML el nombre del elemento deseado, y éste es remplazado por el contenido extraído de la base de datos.
Códigos opcionales
En la práctica, un elemento de contenido se acompaña a menudo con código HTML que sólo debe incluirse si este elemento existe, sin lo cual el formateo y la paginación se vuelven imprecisas.
Por ejemplo, existe una baliza SPIP para indicar el ante-título de un artículo. Sin embargo, numerosos artículos no tienen ante-título.
Completemos el ejemplo precedente:
<BOUCLE_articulos(ARTICLES){id_rubrique}>
#SURTITRE<br>
#TITRE
</BOUCLE_articulos>
que nos da una clásica lista de artículos, ahora con la indicación del título y del ante-título de cada artículo. Pero ¿que pasa si el artículo no tiene ante-título? Obtenemos el código:
«<br>», es decir una cuña seguida de una línea en blanco.
Lo que debemos hacer: mostrar el código «<br>» sólo cuando el artículo tiene un ante-título.
La sintaxis de la baliza SPIP se convierte en:
{{[}} texto opcional antes {{(#BALISE)}} texto opcional despues {{]}}
La baliza que determina el campo SPIP se pone entre paréntesis, y el conjunto de texto condicional entre corchetes. El texto opcional antes y el texto opcional después sólo se verán si existe, en la base de datos, un campo no vacío que corresponde a dicha baliza.
Nuestro ejemplo ahora es así:
<BOUCLE_articulos(ARTICLES){id_rubrique}>
[(#SURTITRE)<br>]
#TITRE
</BOUCLE_articulos>
Y así se obtiene lo que se buscaba: si existe un ante-título en el artículo, se muestra seguido por el <br>; y si no existe, también desaparece el <br>.
Usos avanzados
Se pueden incluir balizas extendidas unas en otras. Así, si en nuestro ejemplo queremos mostrar el logo del artículo sólo si el ante-título está definido, podríamos escribir:
<BOUCLE_articulos(ARTICLES){id_rubrique}>
[ [(#LOGO_ARTICLE)<br>]
(#SURTITRE)]
</BOUCLE_articulos>
Nota: Nunca se puede poner un bucle en el código opcional de una baliza. Sin embargo, si se desea mostrar un bucle en función de la definición o no de una baliza, siempre se puede utilizar <INCLURE()> dentro de un código opcional.
Balizas no ambiguas
Cuando se anidan unos bucles dentro de otros, puede suceder que dos bucles tengan balizas homónimas.
Por ejemplo, en el código siguiente:
<BOUCLE_secciones(RUBRIQUES){id_rubrique}>
<BOUCLE_articulos(ARTICLES){id_rubrique}>
#TITRE
</BOUCLE_articulos>
</BOUCLE_secciones>
la baliza #TITRE designa el título de un artículo. Si quisiéramos mostrar el título de la sección dentro del bucle _articulos, no se podría utilizar #TITRE.
Se puede llamar una baliza homónima de un bucle de nivel superior explicitando el nombre del bucle al que pertenece la baliza. El nombre del bucle se escribirá entre el # y el nombre de la baliza.
La baliza #BALISE del bucle _boucle [1] se escribe entonces de la manera siguiente: #_boucle:BALISE donde _boucle es el nombre del bucle. Por ejemplo:
<BOUCLE_secciones(RUBRIQUES){id_rubrique}>
<BOUCLE_articulos(ARTICLES){id_rubrique}>
#_secciones:TITRE > #TITRE
</BOUCLE_articulos>
</BOUCLE_secciones>
mostrará el título de la sección y luego el del artículo: la baliza #TITRE para el bucle _secciones se transforma en #_secciones:TITRE para que no se confunda con la baliza #TITRE del bucle _articulos.
Filtrar los resultados
Es frecuente que se quiera modificar un elemento extraído de la base de datos, ya sea para obtener una visualización diferente (por ejemplo mostrar el título todo en mayúscula), o para recuperar un valor derivado de ese elemento. (por ejemplo, mostrar el día de la semana correspondiente a una fecha).
En SPIP se pueden aplicar directamente filtros a los elementos extraídos de la base de datos, indicándolo en la sintaxis de las balizas SPIP, lo que nos da:
[ opción antes (#BALIZA|filtreo|filtro2|...|filtroN ) opción después ]
La sintaxis es poner entre paréntesis el nombre de la baliza seguido por el o los filtros sucesivos, separados por una barra vertical (carácter |, conocido con el nombre pipe en el mundo unix)
Nota: En realidad los filtros son funciones PHP. SPIP viene con una serie de filtros ya definidos, pero uno puede agregar sus propios filtros usando las funciones PHP adecuadas (con la condición de que estas funciones sólo utilicen una variable), como veremos más adelante.
He aquí algunos filtros definidos por SPIP:
- majuscules (mayúsculas), pasa el texto a mayúsculas (este filtro es más potente que la función PHP correspondiente, que no funciona con los caracteres acentuados); por ejemplo:
[(#TITRE|majuscules)]
La presente documentación consagra un artículo detallado a los diferentes filtros que vienen con SPIP.
Evitar las transformaciones por SPIP
SPIP aplica transformaciones tipográficas a todos los textos extraídos de la base de datos. En particular, pone espacios insecables antes de ciertos símbolos (puntos y coma, etc.), y analiza los atajos de formateo.
En ciertos casos, puede ser necesario evitar estas transformaciones para recuperar directamente en texto en bruto, tal cual se encuentra en la base de datos. Para eso, es suficiente agregar un asterisco (*) luego de la baliza SPIP. Lo que nos da:
[ opción antes (#BALIZA*|filtro1|filtro2|...|filtroN) opción después]
Los parámetros de las balizas
Ciertas balizas [2] aceptan parámetros. Se pasa la lista de dichos parámetros entre llaves «{» y «}» con comas «,» para separarlos entre si. Por ejemplo: #ENV{lang,fr}.
Un parámetro puede ser una constante u otra baliza. Sólo las balizas en su forma simple (es decir sin códigos opcionales o filtros) pueden ser pasadas como parámetro. Se pueden poner los parámetros entre comillas simples «'...'» si no se quiere que sean interpretados por SPIP.