Sintassi di base
La sintassi semplificata di un ciclo è la seguente:
<BOUCLEn(TIPO){criterio1}{criterio2}...{criterioX}>
* Codice HTML + segnaposti di SPIP
</BOUCLEn>
Nella spiegazione dei cicli e dei segnaposti abbiamo visto che il «Codice HTML + segnaposti di SPIP» si ripeteva tante volte quante erano necessarie al ciclo per estrarre elementi dal database (cioè, una volta, più volte o zero volte).
La linea importante, qui, è:
<BOUCLEn(TIPO){criterio1}{criterio2}...{criterioX}>
- L’elemento BOUCLE è l’istruzione che indica che si tratta di un ciclo SPIP; non è possibile modificarlo; in altre parole, tutti i cicli di SPIP cominciano con l’istruzione BOUCLE.
- L’elemento n è, a scelta, il nome del ciclo o il numero del ciclo. Questo elemento viene scelto dal webmaster per ogni ciclo da lui utilizzato. Più avanti vedremo che è possibile utilizzare più cicli nello stesso modello (è proprio questa l’utilità dell’operazione): pertanto, attribuire un nome al ciclo è indispensabile alla sua identificazione.
Se si decide di attribuire dei numeri ai cicli, la sintassi diventa, per esempio (per il ciclo 5):<BOUCLE5...> ... </BOUCLE5>
Se si decide di attribuire un nome ai cicli (normalmente ciò è più pratico e rende il codice più leggibile), è imperativo far precedere il nome dal simbolo "_" (solitamente chiamato underscore). Per esempio:<BOUCLE_sottorubriche...> ... </BOUCLE_sottorubriche>
- L’elemento (TIPO) è fondamentale: esso indica quale tipo di elementi si desidera estrarre. La sintassi è importante: il TIPO viene indicato tra parentesi (senza spazi), in lettere maiuscole, e questo TIPO deve corrispondere obbligatoriamente a uno dei tipi previsti da SPIP (elencati nella presente documentazione): ARTICLES, RUBRIQUES, AUTEURS, BREVES, ecc.
Quindi, per l’esempio precedente avremo:
<BOUCLE_sottorubriche(RUBRIQUES)...>
...
</BOUCLE_ sottorubriche>- I criteri {criterio1}{criterio2}...{criterioX} indicano secondo quali criteri si desidera selezionare gli elementi del database (mostrare le sotto-rubriche incluse nella rubrica attuale, visualizzare le altre rubriche inserite nel medesimo livello gerarchico della rubrica attuale...) e, al tempo stesso, il modo con cui classificare o selezionare gli elementi (classificare gli articoli secondo la loro data, secondo il titolo... mostrare solo i primi 3 articoli, mostrare solo la metà degli articoli...). Poiché è possibile combinare tra loro i criteri, è molto facile creare delle interrogazioni (query) molto complesse, del tipo: « mostrare l’elenco dei 5 articoli più recenti scritti da questo autore ».
I criteri sono tra parentesi graffe; possono essere separati l’uno dall’altro da uno spazio. Esempio:
<BOUCLE_stesso_autore(ARTICLES) {id_auteur} {par date}{inverse} {0,5}>
...
</BOUCLE_stesso_autore>I diversi criteri e la loro sintassi verrà resa esplicita in seguito, per ogni tipo di ciclo (alcuni criteri si applicano a tutti i tipi di cicli, mentre altri si applicano solo ad alcuni cicli).
Sintassi completa
La sintassi indicata precedentemente può essere completata da elementi condizionali. In effetti, il ciclo precedente mostra in successione gli elementi contenuti all’interno del ciclo. SPIP permette di indicare anche cosa visualizzare prima e dopo il ciclo nel caso in cui esso contenga uno o più risultati, e cosa visualizzare se non vi è alcun elemento.
Quindi abbiamo:
<Bn>
* Codice HTML opzionale prima
<BOUCLEn(TIPO){criterio1}{criterio2}...{criterioX}>
* Codice HTML + segnaposti di SPIP
</BOUCLEn>
* Codice HTML opzionale dopo
</Bn>
* Codice HTML alternativo
<//Bn>
Il codice opzionale prima (preceduto da <Bn>) viene mostrato solo se il ciclo contiene almeno una risposta. Viene visualizzato prima dei risultati del ciclo.
Il codice opzionale dopo (che termina con </Bn>) viene mostrato solo se il ciclo contiene almeno una risposta. Viene visualizzato dopo i risultati del ciclo.
Il codice alternativo (che termina con <//Bn>) viene visualizzato al posto del ciclo (pertanto anche al posto dei codici opzionali prima e dopo) se il ciclo non ha trovato alcuna risposta.
Per esempio, il codice:
<B1>
Questa rubrica contiene gli elementi seguenti:
<ul>
<BOUCLE1(ARTICLES){id_rubrique}>
<li>#TITRE</li>
</BOUCLE1>
</ul>
</B1>
Questa rubrica non contiene articoli.
<//B1>darà come risultato:
- se c’è un solo articolo:
Questa rubrica contiene gli elementi seguenti: <ul> <li>Titolo dell'articolo</li> </ul>
- se ci sono più articoli:
Questa rubrica contiene gli elementi seguenti: <ul> <li>Titolo dell'articolo 1</li> <li>Titolo dell'articolo 2</li> ... <li>Titolo dell'ultimo articolo</li> </ul>
- se non vi è nessun articolo:
Questa rubrica non contiene articoli.
Un po’ di storia: Fino alla versione [SPIP 1.7.2], la maniera con cui SPIP interpretava i cicli vietava di mettere un ciclo tra
<Bn>e<BOUCLEn>. Tuttavia, era possibile aggiungere altri cicli nelle parti opzionali situate dopo la definizione<BOUCLEn...>. Se era veramente necessario inserire un ciclo nella parte opzionale prima, bisognava ricorrere al comando<INCLUDE()>.
Criteri di contesto a cascata
Ogni ciclo esegue la selezione degli elementi estratti dal database in funzione di criteri dati. Alcuni di questi criteri corrispondono al contesto nel quale si trova il ciclo.
Per esempio: se si prevede un ciclo del tipo: "Mostrare gli articoli inclusi in questa rubrica", è necessario sapere di quale rubrica si tratta. Ciò viene definito contesto.
- Il contesto fornito dall’URL
Quando si visita una pagina di un sito SPIP, di solito l’indirizzo contiene una variabile. Per esempio: spip.php?rubrique15 (nelle versioni anteriori a SPIP 1.9, l’URL veniva scritta nel modo seguente: rubrique.php3?id_rubrique=15)
Questa variabile definisce quindi un primo contesto: il ciclo « Mostrare gli articoli inclusi in questa rubrica » deve essere interpretato come: « Mostrare gli articoli della rubrica 15 ».
È ovvio che, con lo stesso codice del modello, se si chiama l’indirizzo: spip.php?rubrique7 (nelle versioni anteriori a SPIP 1.9, l’URL veniva scritta così: rubrique.php3?id_rubrique=7); l’interpretazione di questo ciclo diventerà « Mostrare gli articoli della rubrica 7 ».
- Il contesto fornito dagli altri cicli
All’interno di un ciclo, il contesto viene modificato da ogni elemento del ciclo. Mettendo dei cicli uno dentro l’altro si ottengono contesti nidificati.
Quindi, nella struttura seguente:
<BOUCLE_articoli: mostrare gli articoli di questa rubrica>
Mostrare il titolo dell'articolo
<BOUCLE_autori: mostrare gli autori di questo articolo>
Nome dell'autore
</BOUCLE_autori>
</BOUCLE_articoli>Si deve comprendere che:
- il primo ciclo (BOUCLE_articoli) visualizza gli articoli in funzione della rubrica, secondo il contesto dato dall’URL (id_rubrique=15 per esempio);
- in questo ciclo si ottiene uno o più articoli;
- "all’interno" di ciascuno di questi articoli si ha un contesto diverso (quello dell’articolo, cioè, per esempio, id_article=199);
- il secondo ciclo (BOUCLE_autori), che è inserito all’interno del primo ciclo, dipende da ciascuna delle sue esecuzioni successive (esso viene eseguito per ogni articolo del primo ciclo): "mostrare gli autori di questo articolo" diventa poi "mostrare gli autori del primo articolo", "del secondo articolo" e così via.
Da ciò possiamo notare che se nidifichiamo una serie di cicli otteniamo cicli differenti, inclusi l’uno nell’altro, che dipendono dal risultato dei cicli nei quali si trovano. Infine, il primissimo ciclo (ovvero quello che contiene tutti gli altri) dipende da un parametro indicato nell’indirizzo della pagina.
Cicli inclusi e cicli in successione
Come è possibile includere dei cicli all’interno di altri cicli (in tal caso ogni ciclo incluso dipende dal risultato del ciclo in cui si trova), è anche possibile inserire dei cicli uno di seguito all’altro; i cicli in successione non si influenzano a vicenda.
Per esempio, la pagina di una rubrica è solitamente costituita dagli elementi seguenti:
<BOUCLE_rubrica(RUBRIQUES){id_rubrique}>
<ul>Titolo della rubrica
<BOUCLE_articoli(ARTICLES){id_rubrique}>
<li> Titolo dell'articolo</li>
</BOUCLE_articoli>
<BOUCLE_sotto_rubriche(RUBRIQUES){id_rubrique}>
<li> Titolo della sotto-rubrica </li>
</BOUCLE_sotto_rubriche>
</ul>
</BOUCLE_rubrica>
<ul>Non c'è nessuna rubrica in questo indirizzo.</ul>
<//B_rubrica>Il primo ciclo (BOUCLE_rubrica) dipende dalla variabile passata dall’URL della pagina (per esempio, id_rubrique=15).
I cicli che seguono (BOUCLE_articoli e BOUCLE_sotto_rubriche) sono inseriti all’interno del primo ciclo. Quindi, nel caso non esista nessuna rubrica 15, il primo ciclo non dà alcun risultato (viene mostrato il codice alternativo: "Non c’è nessuna rubrica..."), pertanto i due cicli inclusi vengono completamente ignorati. Invece, se la rubrica 15 esiste, questi due sotto-cicli verranno analizzati.
Possiamo notare anche che questi due cicli si presentano uno dopo l’altro. Pertanto, essi operano in funzione del primo ciclo, ma in maniera indipendente l’uno dall’altro. Se nella rubrica 15 non vi sono articoli (BOUCLE_articoli), verrà comunque mostrato l’elenco delle sotto-rubriche della rubrica 15 (BOUCLE_sotto_rubriche); e viceversa.
Contatori
Due segnaposti permettono di contare i risultati dei cicli.
- #TOTAL_BOUCLE restituisce il numero totale di risultati visualizzati dal ciclo. Lo si può utilizzare all’interno del ciclo, nelle sue parti opzionali — prima e dopo — oppure nella parte alternativa dopo il ciclo.
Per esempio, per visualizzare il numero di documenti associati a un articolo:
<BOUCLE_art(ARTICLES){id_article}>
<BOUCLE_doc(DOCUMENTS) {id_article}></BOUCLE_doc>
[ci sono (#TOTAL_BOUCLE) documenti.]
<//B_doc>
</BOUCLE_art>
Attenzione: se la parte centrale del ciclo non restituisce alcun valore (è il caso del ciclo
<BOUCLE_doc>sopra riportato, la cui funzione è unicamente di contare il numero di risultati), il segnaposto#TOTAL_BOUCLEpuò essere visualizzato solo nella parte alternativa dopo del ciclo (<//B_doc>).
- #COMPTEUR_BOUCLE restituisce il numero di iterazione attuale del ciclo. È per esempio possibile utilizzare tale segnaposto per numerare i risultati:
<BOUCLE_art(ARTICLES) {par date} {inverse} {0,10}>
#COMPTEUR_BOUCLE - #TITRE<br>
</BOUCLE_art>