Cada tipo de loop permite selecionar os elementos da base de dados do SPIP: matérias, seções, notas etc. Cada um desses elementos é, ele próprio, composto de elementos específicos: um título, uma data, um texto etc. No interior de um loop é necessário indicar em que parte do código HTML se insere cada um destes elementos específicos.
É para isso que servem as tags SPIP.
Funcionamento simplificado
Uma tag SPIP é geralmente colocada dentro de um loop (já que é necessário recuperar um componente de uma matéria, de uma seção etc.). O nome dessas tags é geralmente simples, e forneceremos, para cada tipo de loop, a lista completa das tags que podem ser utilizadas nesse contexto.
Uma tag é sempre precedida de um sinal de cardinal (#).
Por exemplo, para exibir uma lista de títulos de matérias:
<BOUCLE_materias(ARTICLES){id_rubrique}>
#TITRE<br>
</BOUCLE_materias>
A cada iteração do loop, a tag SPIP #TITRE será substituída pelo título da matéria em questão:
Título da matéria 1
Título da matéria 2
...
Título da última matéria
Nada de muito complicado: basta indicar no código HTML o nome do elemento desejado, e este é substituído pelo conteúdo recuperado da base de dados.
Códigos opcionais
Na prática, um componente de conteúdo é frequentemente acompanhado de código HTML que só deve ser exibido se o componente existir, ou a diagramação da páginapode tornar-se imprecisa.
Por exemplo, existe uma tag SPIP para indicar o sobretítulo de uma matéria. Porém, diversas matérias podem não ter sobretítulo.
Completando-se o exemplo precedente:
<BOUCLE_materias(ARTICLES){id_rubrique}>
#SURTITRE<br>
#TITRE<br>
</BOUCLE_materias>
que classicamente fornece uma lista das matérias, agora com a indicação do título e do sobretítulo de cada matéria. Mas o que acontece se a matéria não possuir sobretítulo? Obtém-se o código :
«<br>», ou seja, uma linha em branco (uma quebra de linha).
O que precisa ser feito: não exibir o código «<br>» se não existir um sobretítulo para a matéria.
A sintaxe da tag SPIP, então, deve ser :
[ texto opcional anterior (#TAG) texto opcional posterior ]
A tag que determina a opção está colocada entre parêntesis, e o conjunto do texto opcional entre parêntesis rectos. O texto opcional anterior e o texto opcional posterior só serão exibidos se existir, na base de dados, um elemento correspondente a esta tag.
O nosso exemplo torna-se:
<BOUCLE_materias(ARTICLES){id_rubrique}>
[(#SURTITRE)<br>]
#TITRE<br>
</BOUCLE_materias>
Obtém-se assim o resultado desejado: se existir um sobretítulo para esta matéria, ele é exibido seguido de <br>; se não existir sobretítulo, o <br> é ocultado.
- atenção: esta exibição condicional não funciona com as tags dinâmicas (por exemplo, #URL_LOGOUT).
- Após o SPIP 4.0, é possível usar loops nas partes opcionais anteriores ou posteriores de uma tag. Eles devem estar inteiramente contidos numa mesma parte.
Usos avançados
Pode-se aninhar tags extendidas umas nas outras. Assim, se no nosso exemplo quisermos exibir o logo da matéria apenas quando o sobretítulo estiver definido, poderíamos escrever:
<BOUCLE_materiasARTICLES){id_rubrique}>
[[(#LOGO_ARTICLE)<br>](#SURTITRE)<br>]
</BOUCLE_materias>
Nota: Não se pode colocar um loop no código opcional de uma tag. No entanto, se quisermos exibir um loop apenas com base em uma determinada tag, podemos utilizar <INCLURE{...}> no interior de um código opcional.
Tags não-ambíguas
Quando se aninha loops uns nos outros, pode ocorrer que dois loops tenham tags homónimas.
Por exemplo, no código a seguir:
<BOUCLE_secoes(RUBRIQUES){id_rubrique}>
<BOUCLE_materias(ARTICLES){id_rubrique}>
#TITRE
</BOUCLE_materias>
</BOUCLE_secoes>
a tag #TITRE designa o título de uma matéria. No entanto, se se deseja exibir o título da seção no interior do loop _materias, não se poderá usar #TITRE.
Pode-se chamar uma tag homónima de um dos loops envolventes ao se explicitar o nome do loop ao qual a tag pertence. Será, então, necessário especificar o nome do loop entre o # e o nome da tag.
Escreve-se então a tag #TAG do loop _boucle [1] da seguinte maneira: #_boucle:BALISE. Por exemplo:
<BOUCLE_secoes(RUBRIQUES){id_rubrique}>
<BOUCLE_materias(ARTICLES){id_rubrique}>
#_rubriques:TITRE > #TITRE
</BOUCLE_materias>
</BOUCLE_secoes>
exibirá o título da seção e, em seguida, o título da matéria:
a tag #TITRE para o loop _secoes torna-se #_secoes:TITRE para não se confundir com a tag #TITRE do loop _materias.
Filtrar os resultados
É comum querer-se alterar um elemento tirado da base de dados, seja para se obter uma exibição diferente (por exemplo, exibir o título inteiramente em maiúsculas), ou para recuperar um valor decorrente desse elemento (por exemplo, exibir o dia da semana correspondente a uma data).
No SPIP, pode-se aplicar filtros diretamente aos elementos recuperados da base de dados, especificando esses filtros na sintaxe das tags SPIP, que se tornam:
[ opção anterior (#TAG|filtro1|filtro2|...|filtroN ) opção posterior ]
A sintaxe consiste, então, em colocar o nome da tag seguido pelos filtros sucessivos, separados por uma barra vertical (chamada correntemente de pipe), entre parêntesis.
- atenção: a aplicação de filtros não funciona nas tags dinâmicas.
Aqui abaixo, alguns filtros fornecidos pelo SPIP:
- majuscules, converte o texto para maiúsculas (mais eficiente do que a função correspondente do PHP, que não funciona corretamente com caractéres acentuados); por exemplo:
[(#TITRE|majuscules)]
A presente documentação dedica uma matéria aos diferentes filtros fornecidos com o SPIP.
Ignorar o processamento feito pelo SPP
O SPIP aplica um processamento tipográfico a todos os textos retirados da base de dados. Em particular, ele coloca espaços inseparáveis antes de certos símbolos (ponto-e-vírgula, ponto de interrogação etc.) e interpreta os atalhos de formatação.
Em certos casos, você pode precisar ignorar este processamento, de modo a recuperar diretamente o texto simples tal como este se encontra na base de dados. Para tal, basta incluir um asterísco (*) em seguida do nome da tag SPIP. O que daria:
[ opção anterior (#TAG*|filtro1|filtro2|...|filtroN) opção posterior]
(ver #TAG* e #TAG**)
Os parâmetros das tags
Algumas tags [2] aceitam parâmetros. Neste caso, deve-se passar uma lista de parâmetros entre chavetas «{» e «}» com vírgulas «,» para separar cada parâmetro. Por exemplo: #ENV{lang,pt}.
Um parâmetro pode ser uma contante ou uma outra tag. Apenas as tags de formato simples podem ser passadas como parâmetros (i.e. sem códigos opcionais ou filtros). Pode-se colocar os parâmetros entre aspas simples «'...'» se não quisermos que eles sejam interpretados pelo SPIP.