De syntax van de bakens van SPIP

Vereenvoudigde werking

Een baken in SPIP wordt binnen een lus geplaatst (omdat immers duidelijk moet zijn wat het preciese zelemet is wat we willen weergeven). De naam van die bakens is in het algemeen eenvoudig. Voor elke type lus geven we een volledige lijst van de bakens die je (binnen die lus) kunt gebruiken.

Een baken wordt altijd vooraf gegaan door een hekje (#).

Om bijvoorbeeld een lijst te maken van de titels van artikelen kunnen we het volgende schrijven:

<BOUCLE_artikelen(ARTICLES){id_rubrique}>
#TITRE<br />
</BOUCLE_artikelen>

Wanneer de lus wordt uitgevoerd, wordt het baken #TITRE bij ieder resultaat vervangen door de titel van het artikel in kwestie:

Titel van artikel 1<br />
Titel van artikel 2<br />
...
Titel van het laatste artikel<br />

Niets gecompliceerds (behalve misschien de taal): je hoeft binnen de HTML code slechts het baken van het gewenste element te vermelden en het wordt op die plaats weergegeven.

Optionele code

In de praktijk wordt een onderdeel van de inhoud vaak begeleid met HTML code die uitsluitend moet worden toegepast wanner het element aanwezig is, anders riskeren we een foutieve en/of onvolledige pagina-indeling.

Zo bestaat er in SPIP bijvoorbeeld een baken om de boventitel van een artikel weer te geven. Maar dat veld is in SPIP optioneel, dus veel artikelen zullen geen boventitel hebben. We moeten dan mogelijk (afhankelijk van de layout) voorkomen dat een lege regel wordt weergegeven.

We vervolledigen het voorgaande voorbeeld:

<BOUCLE_artikelen(ARTICLES){id_rubrique}>
#SURTITRE<br />
#TITRE<br />
</BOUCLE_artikelen>

dat, zoals verwacht een lijst gaat geven met de vermelding van boventitel en titel van ieder artikel. Maar wat gebeurt er wanneer een artikel geen boventitel heeft? Inderdaad, je krijgt: «<br />», een lege regel (alleen een regelterugloop).

Wat we moeten doen is ervoor zorgen dat de code «<br />» niet wordt weergegeven wanneer een boventitel niet bestaat. De syntax van het SPIP baken wordt:

[ optionele code ervoor (#BALISE) optionele code erna ]

Het baken dat de voorwaarde bepaalt wordt tussen ronde haakjes geplaatst en het geheel waarop de voorwaarde van toepassing is tussen rechte haakjes. De optionele code ervoor en de optionele code erna worden uitsluitend weergegeven wanneer het element dat bij het baken hoort daadwerkelijk in de database wordt aangetroffen.

Ons voorbeeld wordt:

<BOUCLE_artikelen(ARTICLES){id_rubrique}>
[(#SURTITRE)<br />]
#TITRE<br />
</BOUCLE_artikelen>

Zo krijgen we het gewenste resultaat: wanneer een subtitel bestaat voor het artikel, wordt deze weergegeven, gevolgd door een <br />; bestaat hij niet dan wordt ook de <br /> overgeslagen.

-  Let op: deze conditionele weergave functioneert niet het dynamische bakens (zoals bijvoorbeeld: [#URL_LOGOUT{}->art1827]).

Geavanceerd gebruik

Vanaf [SPIP 1.8] kun je bakens bij elkaar insluiten. Als we in ons voorbeeld alleen het logo van het artikel willen weergeven wanneer er een boventitel bestaat, kunnen we schrijven:

<BOUCLE_artikelen(ARTICLES){id_rubrique}>
[[(#LOGO_ARTICLE)<br />](#SURTITRE)<br />]
</BOUCLE_artikelen>

Let op: Er kan nooit een lus worden geplaatst in de optionele code van een baken! Als je toch een lus afhankelijk wilt maken van een bepaalde baken, kun je <INCLURE{...}> binnen de optionele code plaatsen.

Dubbelzinnige bakens

Wanneer een lus binnen een andere lus wordt geplaatst, kan het voorkomen dat bepaalde bakens op beide lussen betrekking hebben; ze hebben soms dezelfde naam!

Kijk bijvoorbeeld naar de volgende code:

<BOUCLE_rubriek(RUBRIQUES){id_rubrique}>
     <BOUCLE_artikelen(ARTICLES){id_rubrique}>
         #TITRE
     </BOUCLE_artikelen>
</BOUCLE_rubriek>

waar het baken #TITRE de titel van het artikel moet weergeven. Maar wat nou als we de titel van de rubriek binnen de lus _artikelen willen weergeven. We kunnen het baken #TITRE daar niet gebruiken.

Vanaf [SPIP 1.8] kunnen we in het geval van homonieme bakens de naam van de lus waartoe het baken behoort toevoegen. De naam van de lus moet daarvoor samen met een dubbele punt worden geplaatst tussen de # en de naam van het baken.

We maken een baken #BAKEN van de lus _lus [1] op de volgende manier: #_lus:BAKEN. Of in ons voorbeeld:

<BOUCLE_rubriek(RUBRIQUES){id_rubrique}>
     <BOUCLE_artikelen(ARTICLES){id_rubrique}>
         #_rubriek:TITRE > #TITRE
     </BOUCLE_artikelen>
</BOUCLE_rubriek>

krijgen we nu als resultaat de titel van de rubriek, gevolgd door > en de titel van het artikel. Het baken #TITRE voor lus _rubriek wordt #_rubriek:TITRE om niet te worden verward met het baken #TITRE van de lus _artikelen.

De resultaten filteren

Vaak willen we een uit de database onttrokken element aanpassen, ofwel ten behoeve van een aangepaste weergave (bijvoorbeeld de titel volledig in hoofdletters weergeven), of om een afgeleide waarde van het element weer te geven (bijvoorbeeld de dag van een week bij een datum).

In SPIP kunnen deze filters direct op de uit de database gehaalde elementen worden toegepast. We kunnen ze namelijk opnemen in de syntax van de bakens van SPIP, wat resulteert in:

[ optionele code ervoor (#BAKEN|filter1|filter2|...|filtern) optionele code erna ]

De syntax bestaat dus uit het laten volgen van het baken door de achtereenvolgende filters, ieder voorafgegaan door een verticale streep [2]. Baken en filters moeten samen tussen ronde haakjes zijn geplaatst.

-  let op: het toepassen van filters werkt niet op dynamische bakens.

Dit zijn enkele door SPIP geleverde filters:

-  majuscules zet de tekst in hoofdletters (en is krachtiger dan de corresponderende PHP functie, die niet goed werkt op tekens let een accent); bijvoorbeeld:

[(#TITRE|majuscules)]

-  justifier lijnt de tekst aan beide zijden uit (zoals ook <div style="text-align:justify"> zou doen); bijvoorbeeld:

[(#TEXTE|justifier)]

De huidige documentatie wijdt een artikel aan de verschillende door SPIP geleverde filters.

De bewerking door SPIP verhinderen

SPIP past bepaalde typografische handelingen toe op uit de database onttrokken tekst. Zo voegt het (in de Franse taal) spaties toe vóór bepaalde leestekens en analyseert het de opmaakcodes die zijn opgenomen.

In sommige gevallen is die bewerking niet wenselijk, bijvoorbeeld omdat we direct de "ruwe" tekst uit de database willen weergeven. Hiervoor volstaat het om een sterretje (*) achter het baken te plaatsen. Dit geeft:

[ optionele code ervoor (#BAKEN*|filter1|filter2|...|filtern) optionele code erna ]

(zie #BAKEN* en #BAKEN**)

De parameters van de bakens

Vanaf [SPIP 1.8] accepteren bepaalde bakens [3] parameters. Je kunt zo een lijst van parameters tussen accolades «{» en «}» gescheiden door een komma «,» doorgeven. Bijvoorbeeld: #ENV{lang,fr}.

Zo’n parameter kan een constante zijn, maar ook een ander baken. Maar alleen "kale" bakens kunnen als parameter worden doorgegeven (dus geen optionele code of filters). Je kunt de parameters tussen enkele aanhalingstekens «'...'» zetten om te voorkomen dat ze door SPIP worden geïnterpreteerd.