La sintaxi dels bucles

Sintaxi de base

La sintaxi simplificada d’un bucle és la següent:

<BOUCLEn(TYPE){critère1}{critère2}...{critèrex}>
* Code HTML + etiquetes SPIP
</BOUCLEn>

Hem vist a l’explicació sobre els bucles i les etiquetes, que el «Codi HTML + etiquetes SPIP» es repetia tantes vegades com elements extrets de la base de dades quan s’executa el bucle (és a dir una vegada, moltes vegades o zero vegades).

La línia important, aquí, és:
<BOUCLEn(TYPE){critère1}{critère2}...{critèrex}>

-  L’element BOUCLE és l’ordre que indica que es tracta d’un bucle SPIP; no es pot modificar; dit d’una altra manera, tots els bucles de l’SPIP comencen per la instrucció BOUCLE.

-  L’element n és el nom o el número del bucle, lliurement escollit pel webmestre, per cada bucle que utilitza (atenció: cal tenir cura d’anomenar els seus bucles només amb caràcters alfanumèrics no accentuats i el guió-baix «underscore»; és a dir, caràcters del tipus [a-zA-Z0-9_]. Es veurà, més endavant, que és possible (és també tot l’interès de la maniobra) utilitzar diversos bucles en un mateix esquelet: donar-los-hi un nom és, per tant, indispensable per identificar-los.

Si decidiu enumerar els vostres bucles, la sintaxi esdevé, per exemple (pel bucle 5):
<BOUCLE5...> ... </BOUCLE5>

Si decidiu donar un nom als vostres bucles (és generalment més pràctic, el vostre codi és més llegible), és necessari forçosament fer precedir aquest nom pel símbol «_» (que s’anomena habitualment underscore). Per exemple:
<BOUCLE_sousrubriques...> ... </BOUCLE_sousrubriques>

-  L’element (TYPE) és primordial: indica quin tipus d’elements es volen recuperar. La sintaxi és important: el TYPE s’indica entre parèntesi (sense espais), en majúscules i aquest TYPE ha de correspondre obligatòriament a un dels types que es preveuen a SPIP (que trobarem en la present documentació): ARTICLES, SECCIONS, AUTORS, BREUS, etc.

Per l’exemple anterior tindríem, per tant:

<BOUCLE_sousrubriques(RUBRIQUES)...>
...
</BOUCLE_sousrubriques>

-  Les critères {critère1}{critère2}...{critèrex} indiquen al mateix temps segons quins criteris es vol seleccionar els elements de la base de dades (mostrar les sub-seccions incloses en aquesta secció, mostrar les altres seccions instal·lades al mateix nivell jeràrquic que la present secció...), i la manera com es classificaran o seleccionaran els elements (classificar els articles segons la seva data, el seu títol... mostrar només els 3 primers articles, ensenyar-nos la meitat dels articles...). Com que es poden combinar els criteris, es pot fabricar molt fàcilment peticions molt poderoses, del tipus «mostrar la llista dels 5 articles més recents escrits per un autor determinat».

Els criteris van entre claus; poden estar separats uns dels altres mitjançant un espai. Exemple :

<BOUCLE_meme_auteur(ARTICLES) {id_auteur} {par date}{inverse} {0,5}>
...
</BOUCLE_meme_auteur>

Els diferents criteris i la seva sintaxi s’explicaran més detalladament a continuació, per a cadascun dels tipus de bucle (certs criteris funcionen per tots els tipus de bucles, altres són específics només per alguns).

Sintaxi completa

La sintaxi indicada anteriorment pot ser completada per elements condicionals. En efecte, el bucle precedent mostra successivament els elements continguts a l’interior del bucle. SPIP permet a més especificar què es vol mostrar abans i després del bucle en el cas que contingui un o diversos resultats i què es mostrarà si no hi ha cap element.

Això dóna:
<Bn>
* Code HTML optionnel avant
<BOUCLEn(TYPE){critère1}{critère2}...{critèrex}>
* Code HTML + balises SPIP
</BOUCLEn>
* Code HTML optionnel après
</Bn>
* Code HTML alternatif
<//Bn>

El codi opcional abans (precedit de <Bn>) només es mostra quan el bucle conté com a mínim una resposta. És mostra abans dels resultats del bucle.

El codi opcional desprès (acabat per </Bn>) només es mostra quan el bucle conté com a mínim una resposta. Es mostra després dels resultats del bucle.

El codi alternatiu (acabat per <//Bn>) es mostra en lloc del bucle (i, per tant, igualment al lloc dels codis opcionals abans i després) si el bucle no mostra res (sigui perquè la base de dades no ha proporcionat cap resposta, o bé perquè el codi que utilitza aquestes respostes al bucle no mostra res).

Per exemple, el codi:

<B1>
  Aquesta secció conté els següents elements:
  <ul>
    <BOUCLE1(ARTICLES){id_rubrique}>
    <li>#TITRE</li>
    </BOUCLE1>
  </ul>
</B1>
  Aquesta secció no conté cap article.
<//B1>

<B1>
 
dóna els resultats següents:

- {{si només hi ha un article:}}
<quote><code> Aquesta secció conté els següents elements:
 <ul>
   <li>Títol de l'article</li>
</ul>

-  si hi ha diversos articles:

 Aquesta secció conté els següents elements:
 <ul>
   <li>Títol de l'article 1</li>
   <li>Títol de l'article 2</li>
   ...
   <li>Títol de l'últim article</li>
</ul>

-  si no hi ha cap article:

Aquesta secció no conté cap article.

Històric: Fins a [SPIP 1.7.2], la manera com SPIP interpretava els bucles prohibia posar un bucle entre <Bn> i <BOUCLEn>. No obstant, era possible posar bucles suplementaris a les parts opcionals situades després de la definició <BOUCLEn...>. Si havíeu d’instal·lar forçosament un bucle dins la part opcional abans, era necessari passar una ordre <INCLURE()>.

Criteris d’entorn en cascada

Cada bucle realitza la selecció dels elements extrets de la base de dades en funció dels criteris. Aquests criteris corresponen a l’entorn en el que es troba el bucle.

Per exemple: si es preveu un bucle de l’estil «Mostrar els articles inclosos en aquesta secció», és necessari saber de quina secció es tracta. És el que s’anomena l’entorn.

-  L’entorn proporcionat per l’URL

Quan es visita una pàgina d’un lloc SPIP, la seva adreça té, generalment, una variable. Per exemple: spip.php?rubrique15 (abans d’SPIP 1.9, l’url s’escrivia: rubrique.php3?id_rubrique=15)

Aquesta variable defineix, doncs, un primer entorn: el bucle «Mostrar els articles inclosos en aquesta secció» s’ha d’entendre com «Mostrar els articles de la secció 15».

Clarament, amb el mateix codi d’esquelet, si es crida l’adreça: spip.php?rubrique7 (abans d’SPIP 1.9, l’url s’escrivia: rubrique.php3?id_rubrique=7); la interpretació d’aquest bucle esdevindrà «Mostrar els articles de la secció 7».

-  L’entorn proporcionat pels altres bucles

A l’interior d’un bucle, l’entorn és modificat per cada element del bucle. Col·locant bucles uns dins dels altres, s’hereta també uns entorns imbricats els uns amb els altres.

Així, en l’estructura següent:

<BOUCLE_articles: mostrar els articles d'aquesta secció>
  Mostrar el títol de l'article
  <BOUCLE_auteurs: mostrar els autors d'aquest article>
    Nom de l'autor
  </BOUCLE_auteurs>
</BOUCLE_articles>

Hem de comprendre que:
-  el primer bucle (BOUCLE_articles) mostra els articles en funció de la secció, segons l’entorn proporcionat per l’URL (id_rubrique=15 per exemple);
-  en aquest bucle, s’obtenen un o diversos articles;
-  «a l’interior» de cadascun d’aquests articles, hi ha un entorn diferent (el de l’article, és a dir, per exemple, id_article=199);
-  el segon bucle (BOUCLE_auteurs), que es troba a l’interior del primer bucle, depèn per a cadascuna de les seves execucions successives (s’executa per cada article del primer bucle): «mostrar els autors d’aquest article» esdevé successivament «mostrar els autors del primer article», «del segon article», etc.

Veiem que, per la imbricació de bucles successius, s’obtenen diferents bucles, inclosos uns dins dels altres, que depenen del resultat dels bucles en els quals estan situats. I, finalment, tot el primer bucle (aquell que conté tots els altres) depèn d’un paràmetre fixat a l’adreça de la pàgina.

Bucles inclosos i bucles successius

Si bé, com acabem de veure, podem incloure bucles uns dins dels altres (cada bucle inclòs depèn del resultat del bucle a l’interior del qual es troba), també podem incloure bucles uns a continuació dels altres; en aquest cas, els bucles successius no influeixen els uns amb els altres.

Per exemple, la pàgina d’una secció es compon, normalment, dels elements següents:

<BOUCLE_rubrique(RUBRIQUES){id_rubrique}>
  <ul>Títol de la secció
  <BOUCLE_articles(ARTICLES){id_rubrique}>
    <li> Títol de l'article</li>
  </BOUCLE_articles>
  <BOUCLE_sous_rubriques(RUBRIQUES){id_rubrique}>
    <li> Títol de la subsecció </li>
  </BOUCLE_sous_rubriques>
  </ul>
</BOUCLE_rubrique>
  <ul>No hi ha cap secció en aquesta adreça.</ul>
<//B_rubrique>

El primer bucle (BOUCLE_rubrique) depèn de la variable passada a l’URL de la pàgina (id_rubrique=15 per exemple).

Els bucles següents (BOUCLE_articles i BOUCLE_sous_rubriques) estan instal·lats a l’interior del primer bucle. Depenen dels resultats d’aquest, però són independents un de l’altre. D’aquesta manera, si no existeix la secció 15, el primer bucle no ens dóna cap resultat (es mostra el codi alternatiu «No hi ha cap secció...»), i , per tant, els dos bucles inclosos són totalment ignorats. En canvi, si existeix una secció 15, s’analitzaran els dos sub-bucles.

Podem constatar, igualment, que els dos bucles es presenten un desprès de l’altre. Es posen en marxa en funció del primer bucle, però independentment l’un de l’altre. Si no troba cap article a la secció 15 (BOUCLE_articles), mostrarà de totes maneres la llista de les sub-seccions de la secció 15 (BOUCLE_sous_rubriques) i a l’inrevés.

Comptadors

Dues etiquetes permeten comptar els resultats en els bucles.

-  #TOTAL_BOUCLE retorna el nombre total de resultats mostrats pel bucle. El podeu utilitzar dins del bucle o dins les seves parts opcionals -abans i després- o també a la part alternativa desprès del bucle. Per exemple, per mostrar el número de documents associats a un article:

<BOUCLE_art(ARTICLES){id_article}>
  <BOUCLE_doc(DOCUMENTS) {id_article}></BOUCLE_doc>
    [hi ha (#TOTAL_BOUCLE) document(s).]
  <//B_doc>
</BOUCLE_art>

Atenció: si la part central del bucle no retorna res (és el que passa amb el bucle <BOUCLE_doc> que hi ha mès amunt, que només serveix per comptar el nombre de resultats), el #TOTAL_BOUCLE només es podrà enganxar dins la part alternativa després del bucle (<//B_doc>).

-  #COMPTEUR_BOUCLE retorna el numéro de la repetició actual del bucle. Es pot fer servir, per exemple, per numerar els resultats:

<BOUCLE_art(ARTICLES) {par date} {inverse} {0,10}>
#COMPTEUR_BOUCLE - #TITRE<br>
</BOUCLE_art>