Ogni tipo di ciclo permette di selezionare elementi del database di SPIP: articoli, rubriche, brevi, eccetera. Ognuno di questi elementi è costituito a sua volta da elementi precisi: un titolo, una data, un testo, ecc. All’interno di un ciclo bisogna quindi poter indicare in quale posto del codice HTML si mette questo o quell’elemento specifico.
A tal fine utilizzeremo i segnaposti di SPIP.
Funzionamento semplificato
Un segnaposto di SPIP si inserisce all’interno di un ciclo (poiché è necessario sapere se si vuole recuperare un elemento di un articolo, di una rubrica, ecc.). Di solito, il nome di questi segnaposti è semplice, e noi daremo l’elenco completo dei segnaposti che si possono utilizzare per ogni tipo di ciclo.
Un segnaposto è sempre preceduto dal segno cancelletto (#).
Per esempio, visualizziamo un elenco di nomi di articoli:
<BOUCLE_articoli(ARTICLES){id_rubrique}>
#TITRE<br />
</BOUCLE_articolo>
Quando il ciclo viene eseguito, il segnaposto di SPIP #TITRE verrà sostituito ogni volta dal titolo dell’articolo in questione:
Titolo dell’articolo 1<br /> Titolo dell’articolo 2<br /> ... Titolo dell'ultimo articolo<br />
Nulla di complicato, quindi. Ci si accontenta di indicare all’interno del codice HTML il nome dell’elemento desiderato, e questo viene sostituito dal contenuto estratto dal database.
Codici opzionali
Nella pratica, un elemento del contenuto è spesso accompagnato dal codice HTML che deve essere mostrato solo se quell’elemento esiste, senza il quale l’impaginazione diventa imprecisa.
Per esempio: esiste un segnaposto di SPIP per indicare l’occhiello di un articolo. Ora, molti articoli non hanno nessun occhiello.
Completiamo l’esempio precedente:
<BOUCLE_articoli(ARTICLES){id_rubrique}>
#SURTITRE<br />
#TITRE<br />
</BOUCLE_articoli>
che, di solito, ci dà un elenco di articoli, con l’indicazione del titolo e dell’occhiello di ogni articolo. Ma cosa succede se l’articolo non ha l’occhiello? Si ottiene il codice:
«<br />», ovvero una riga bianca (un ritorno a capo).
Quel che noi dobbiamo fare è di non mostrare il codice «<br />» se non è presente l’occhiello per quell’articolo.
Pertanto, la sintassi del segnaposto di SPIP diventa:
[ testo opzionale prima (#SEGNAPOSTO) testo opzionale dopo ]
Il segnaposto che determina l’opzione viene incluso tra parentesi, e l’insieme del testo condizionale è tra parentesi quadre. Il testo opzionale prima e il testo opzionale dopo vengono mostrati solo se nel database è presente un elemento corrispondente a questo segnaposto.
Il nostro esempio diventa:
<BOUCLE_articoli(ARTICLES){id_rubrique}>
[(#SURTITRE)<br />]
#TITRE<br />
</BOUCLE_articoli>
Si ottiene quindi il risultato cercato: se è presente un occhiello per questo articolo esso viene mostrato e seguito da <br />; se invece l’occhiello non esiste viene nascosto anche <br />.
Utilizzi avanzati
A partire dalla versione [SPIP 1.8] è possibile nidificare i segnaposti estesi gli uni negli altri. Quindi, se nel nostro esempio si desidera visualizzare il logo dell’articolo solo se l’occhiello contiene del testo, potremmo scrivere:
<BOUCLE_articoli(ARTICLES){id_rubrique}>
[[(#LOGO_ARTICLE)<br />](#SURTITRE)<br />]
</BOUCLE_articoli>
Nota: non è mai possibile mettere un ciclo nel codice opzionale di un segnaposto. Tuttavia, se si vuole visualizzare un ciclo in base a un determinato segnaposto, è possibile utilizzare <INCLUDE{...}> all’interno di un codice opzionale.
Segnaposti non ambigui
Quando si nidificano cicli potrebbe succedere che due cicli abbiano segnaposti omonimi.
Per esempio, nel codice seguente:
<BOUCLE_rubriche(RUBRIQUES){id_rubrique}>
<BOUCLE_articoli(ARTICLES){id_rubrique}>
#TITRE
</BOUCLE_articoli>
</BOUCLE_rubriche>
il segnaposto #TITRE indica il titolo di un articolo. Pertanto, se si desidera visualizzare il titolo della rubrica all’interno del ciclo _articoli, non sarebbe possibile utilizzare #TITRE.
Dalla versione [SPIP 1.8], è possibile chiamare un segnaposto omonimo di uno dei cicli nidificati esplicitando il nome del ciclo al quale il segnaposto appartiene. È quindi necessario specificare il nome del ciclo tra il carattere # e il nome del segnaposto.
Quindi, si scrive il segnaposto #SEGNAPOSTO del ciclo _nomeciclo [1] nella maniera seguente: #_nomeciclo:SEGNAPOSTO. Per esempio:
<BOUCLE_rubriche(RUBRIQUES){id_rubrique}>
<BOUCLE_articoli(ARTICLES){id_rubrique}>
#_rubriche:TITRE > #TITRE
</BOUCLE_articoli>
</BOUCLE_rubriche>
visualizza il titolo della rubrica, un > e il titolo dell’articolo:
il segnaposto #TITRE per il ciclo _rubriche diventa #_rubriche:TITRE per non essere confuso con il segnaposto #TITRE del ciclo _articoli.
Filtrare i risultati
Spesso si vorrà modificare un elemento estratto dal database, o per ottenere una visualizzazione diversa (per esempio, visualizzare il titoto tutto in maiuscolo), oppure per recuperare un valore attinente a questo elemento (per esempio, mostrare il giorno della settimana corrispondente a una tale data).
Con SPIP possiamo applicare dei filtri direttamente agli elementi recuperati dal database, indicandoli nella sintassi dei segnaposti di SPIP, che diventa quindi:
[ opzione prima (#SEGNAPOSTO|filtro1|filtro2|...|filtron) opzione dopo ]
La sintassi è cioè far seguire il nome del segnaposto, tra parentesi, dai filtri, separati da una barra verticale (solitamente chiamata pipe).
Alcuni filtri forniti da SPIP:
- majuscules, cambia il testo in lettere maiuscole (più potente dell’analoga funzione PHP, che non funziona correttamente con i caratteri accentati); per esempio:
[(#TITRE|majuscules)]
- justifier, visualizza il testo giustificato (cioè, <P align=justify>); per esempio:
[(#TEXTE|justifier)]
La presente documentazione dedica un articolo ai diversi filtri forniti con SPIP.
Aggirare il trattamento di testi di SPIP
SPIP applica delle regole tipografiche a tutti i testi estratti dal database. In particolare, esso inserisce degli spazi indivisibili prima di alcuni simboli (punto e virgola, punto interrogativo, ecc.), e analizza le scorciatoie tipografiche.
In alcuni casi si potrebbe aver bisogno di aggirare questa funzionalità allo scopo di recuperare direttamente il testo puro così com’è nel database. A tal fine, è sufficiente aggiungere un asterisco (*) dopo il segnaposto di SPIP. Quindi avremo:
[ opzione prima (#SEGNAPOSTO*|filtro1|filtro2|...|filtron) opzione dopo ]
I parametri dei segnaposti
Dalla versione [SPIP 1.8], alcuni segnaposti [2] accettano dei parametri. Pertanto si passa un elenco di parametri tra parentesi graffe « { » e « } » con virgole « , » per separare ogni paramatro. Per esempio: #ENV{lang,fr}.
Un parametro può essere una costante o un altro segnaposto. Solo i segnaposti in formato semplice possono essere passati come parametri (cioè, niente codice opzionale o filtri). È possibile mettere i parametri tra virgolette singole "'...'" se si desidera che essi non siano interpretati da SPIP.