home | sitemap

HTML besturen: TMPL_...

Om een html bestand geschikt te maken voor het cms moeten hier en daar zogenaamde variabelen worden ingevoegd. Naast variabelen die verplicht zijn (zonder deze werkt het cms niet) zijn er standaard variabelen die het cms van een waarde voorziet en die een vormgever vrij kan gebruiken en door de vormgever zelf te definiëren variabelen die weer door een redacteur van een waarde kunnen worden voorzien.

TMPL_VAR

Alle variabelen worden via een zogenaamde variabele-tag ingevoegd:

<!-- TMPL_VAR NAME="xxx" -->

waarin xxx de naam van de variabele is. TMPL_VAR verteld het cms dat er een variabele ingevoegd moet worden, de waarde van NAME welke variabele dat is. Met

<!-- TMPL_VAR NAME="titel" -->

wordt bijvoorbeeld de titel van een pagina bedoeld.

Het cms vervangt al deze variabele-tags met de actuele waarde vlak voordat de pagina aan de redacteur wordt getoond of wordt gepubliceerd. Is de titel van een pagina bijvoorbeeld 'Ons bedrijf', dan heeft de variabele de 'waarde' 'Ons bedrijf' en wordt de variabele-tag met deze tekst vervangen. Dus

Ons bedrijf

Een variabele-tag mag overal in het html bestand voorkomen. Een logische plek voor een titel van de pagina zou bijvoorbeeld kunnen zijn in de header van de pagina:

...
<div id="header">
...
<span id="pagetitle"><!-- TMPL_VAR NAME="titel" --></span>
...

Na vervangen van de variabele-tag met de echte waarde wordt dit

...
<div id="header">
...
<span id="pagetitle">Ons bedrijf</span>
...

Heeft een variabele geen waarde, dan wordt de variabele-tag logischerwijs vervangen met 'niets':

...
<div id="header">
...
<span id="pagetitle"></span>
...

Default waarde

Als een variabele geen waarde heeft, dan kun je eventueel ook een default waarde laten gebruiken. Dit doe je door het attribuut DEFAULT te gebruiken:

...
<!-- TMPL_VAR NAME="mijnvariabele" DEFAULT="mijn default waarde" -->
...

NB: Het DEFAULT-attribuut werkt alleen voor eigen stijl-variabelen en niet voor de standaard variabelen. Gebruik voor deze laatste eventueel de TMPL_IF/TMPL_ELSE constructie (Zie volgende hoofdstuk.)

HTML 'escapen'

Als je wilt voorkomen dat de redacteur zelf html kan invoegen, dan kun je er voor zorgen dat alle html-tekens worden vervangen door de 'veilige' variant. Een > wordt dan bijvoorbeeld &gt;. Om de inhoud te 'escapen' gebruik je het ESCAPE attribuut:

...
<!-- TMPL_VAR NAME="mijnvariabele" ESCAPE="HTML" -->
...

Wordt de inhoud van de variabele als string gebruikt in javascript, gebruik dan JS in plaats van HTML als waarde voor ESCAPE:

...
var str = "<!-- TMPL_VAR NAME="mijnvariabele" ESCAPE="JS" -->";
...

Dit zorgt er voor dat de tekens als ', " en <enter>, etc. worden vervangen door \', \", \n, etc.

Het is ook mogelijk url's te escapen. Gebruik dan waarde URL:

...
<a href="/link.html?url=<!-- TMPL_VAR NAME="page_url" ESCAPE="URL" -->">Link naar ... </a>
...

Uitvoer inkorten

Het is ook mogelijk de uitvoer in te korten met het MAXLEN attribuut, eventueel gecombineerd met een string dat na inkorten moet worden toegevoegd. Om de uitvoer bijv. maximaal 20 karakters lang te laten zijn:

...
<p class="intro"><!-- TMPL_VAR NAME="tmplTitle" MAXLEN="20" --></p>
...

Stel dat tmplTitle "Dit is een zin die we gaan inkorten" bevat, dan is de uitkomst

...
<p class="intro">Dit is een zin die w</p>
...

Door een gewenste string aan MAXLEN mee te geven kunnen we de tekst netjes laten afkappen, bijv. met een '...' (maar elke andere tekenreeks mag dus ook):

...
<p class="intro"><!-- TMPL_VAR NAME="tmplTitle" MAXLEN="20 ..." --></p>
...

wordt dan 

...
<p class="intro">Dit is een zin di...</p>
...

Merk op dat de zin met de lengte van de extra string aan het eind wordt ingekort. De uitkomst is dus nooit langer dan via MAXLEN opgegeven.

Tip: MAXLEN converteert de uitvoer altijd eerst naar platte tekst. HTML-opmaak, etc. gaat dus verloren!...maar dat kan eventueel handig zijn als je juist van HTML platte tekst wilt maken. Geef dan gewoon een MAXLEN op die zeker te weten groter is dan te verwachten tekst (bijv. 100000). De tekst wordt dan niet ingekort, maar bevat geen HTML-opmaak meer.

HOOFD- en kleine letters

Via het attribuut TRANSFORM kan de uitvoer voor wat betreft hoofd- en kleine letters worden aangepast. Om de uitvoer compleet in hoofdletters weer te geven:

...
<h1><!-- TMPL_VAR NAME="tmplTitle" TRANSFORM="uppercase" --></h1>
...

Voor TRANSFORM kunnen de volgende waardes (samen) worden gebruikt:

Zoals gezegd, de waardes kunnen ook samen worden gebruikt. Om van 'DIT IS EEN TEST' bijvoorbeeld 'Dit Is Een Test' te maken dienen lc en ucwords in die volgorde te worden gecombineerd:

...
<h1><!-- TMPL_VAR NAME="tmplTitle" TRANSFORM="lc ucwords" --></h1>
...

Vervangen

Via het attribuut TRANSFORM kan ook worden gezocht en vervangen met reguliere expressies. Neem als waarde één of meerdere replace constructies op, bijvoorbeeld:

Vervang abc met niks (verwijderen):
<!-- TMPL_VAR NAME="tmplVar" TRANSFORM="replace: abc" -->
Voorbeeld: '123 abc 456 def' wordt '123  456 def'

Vervang abc met def:
<!-- TMPL_VAR NAME="tmplVar" TRANSFORM="replace: abc def" -->
Voorbeeld: '123 abc 456 def' wordt '123 def def 456'

Vervang een reeks van 1 of meerdere cijfers (\d+) met een _:
<!-- TMPL_VAR NAME="tmplVar" TRANSFORM="replace: \d+ _" -->
Voorbeeld: '123 abc 456 def' wordt '_ abc 456 def'

Met de toevoegen (?g) voor de reguliere expressie wordt het vervangen uitgevoerd tot alle mogelijkheden zijn vervangen:
<!-- TMPL_VAR NAME="tmplVar" TRANSFORM="replace: (?g)\d+ _" -->
Voorbeeld: '123 abc 456 def' wordt '_ abc _ def'

Vervang a met d en b met e:
<!-- TMPL_VAR NAME="tmplVar" TRANSFORM="replace: a d replace: b e" -->
Voorbeeld: '123 abc 456 def' wordt '123 dec 456 def'

Door de reguliere expressie vooraf te laten gaan met (?g) kun je er voor zorgen dat het vervangen wordt uitgevoerd zolang er wat te vervangen valt. Verder kun je met (?i) het matchen van de reguliere expressie case-insensitive maken. (?g) en (?i) kun je ook combineren tot (?gi).

Rekenen

Met TRANSFORM kan ook worden gerekend, mits de uitvoer een getal is. Daarmee kun je (eenvoudige) berekeningen laten uitvoeren, bijv. om een opgegeven getal te verhogen of te converteren. Wil je bijv. de redacteur de grootte van het font laten beinvloeden en moet een H1 altijd 1,5x groter zijn, gebruik dan bijv.

<style type="text/css">
#tekst { 
  font-size: <!-- TMPL_VAR NAME="fontsize" -->px; 
} 
#tekst h1 { 
  font-size: <!-- TMPL_VAR NAME="fontsize" TRANSFORM="calc: v*1.5" -->px; 
}
</style>

De waarde van de variabele (in dit geval fontsize) heeft in de berekening de naam v. In de berekening kun je bewerkingen gebruiken als + - * / en haakjes ().

De uitkomst van de berekening kan eventueel worden afgerond en/of in elke gewenste notatie worden weergegeven. Dit wordt gedaan door achter de berekening de gewenste notatie op te nemen in de vorm %-w.dx waarin w de gewenste breedte aangeeft (de - voor de w geeft aan dat het gegeven dan links uitgelijnd moet worden), d het aantal posities rechts van het decimaalteken en x het gewenste type. De volgende typen zijn mogelijk:

c: het karakter met dat nummer
s: een tekenreeks
d: een heel getal (eventueel met een - teken)
u: een heel getal (altijd zonder - teken)
o: een getal in octaal formaat
x: een getal in hexdecimaal formaat
e: een floating-point getal, in wetenschappelijk formaat
f: een floating-point getal, in vast decimaal formaat

Voorbeelden:

De waarde 7,12 met notatie %6.2f geeft '     7.12'
De waarde 7,12 met notatie %-6.2f geeft ' 7.12     ' (min-teken, dus links uitlijnen)
De waarde 7.127 met notatie %6.2f geeft '     7.13'
De waarde 7.12 met notatie %.2f geeft '7.12' (geen breedte, dus geen uitlijning)
De waarde 10 met notatie %x geeft '0xa'

Alles na de berekening wordt gezien als opmaak voor de notatie, er kan dus ook een complete zin worden opgenomen, bijv.

<!-- TMPL_VAR NAME="verbruik" TRANSFORM="calc: 100/v Het verbruik van de auto is 1 op %.2f km" -->

geeft als resultaat

Het verbruik van de auto is 1 op 8.06 km

Meerdere TRANSFORM's

Meerdere TRANSFORM opties als replace, calc en hoofd/kleine letters vervangen kunnen worden gecombineerd door ze te scheiden met een enter. Dit maakt dat de TRANSFORM="..." over meerdere regels loopt wat er misschien gek uitziet, maar wel werkt ;-). Voorbeeld:

<!-- TMPL_VAR NAME="xyz" TRANSFORM="replace: abc def
uc
replace: xcms_ascii" -->

Bovenstaande maakt dat in de waarde van variabele xyz eerst abc wordt vervangen met def, vervolgens wordt alles omgezet naar hoofdletters en worden als laatste html entities (als &nbsp;, &euml;, etc) omgezet naar gewone ASCII tekst.

Een ander voorbeeld om het verbruik van een voertuig van x liter op de 100km om te rekenen naar 1 op y:

<!-- TMPL_VAR NAME="verbruik_liter_100km" TRANSFORM="replace: , .
calc: 100/v %.2f
replace: \. ," -->

'replace: , .' maakt van bijv. 12,4 12.4 (met een punt i.p.v. komma), 'calc: 100/v %.2f' rekent het om naar 1 op de 8,064516129032258 (de %.2f rond de uitkomst af op 2 cijfers achter komma = 8.06) en de laatste 'replace: \. ,' maakt van de uitkomst 8.06 weer 8,06

Formateren

De uitvoer kan ook worden geformateerd door het attribuut FORMAT mee te geven met de gewenste opmaak. Dit is vooralsnog alleen mogelijk voor datums. Bijvoorbeeld:

<!-- TMPL_VAR NAME="datum" FORMAT="date: %D2 %d %M %jj" -->

levert voor de datum 3 maart 2011 op

do 3 maart 11

Lees meer over de mogelijk opties voor de formatering van een datum.

Tip: in plaats van een formaat kun je ook ago opgeven. Het cms rekent de datum dan om in hoe lang het geleden is, met uitkomsten als bijv. '10 minuten geleden' of 'gisteren' of '2 maanden geleden'.

TMPL_IF en TMPL_UNLESS

Het feit dat een variabele wel of geen waarde heeft kan ook worden gebruikt om dynamisch de inhoud van de getoonde html pagina te bepalen. Bijvoorbeeld: "Als de variabele titel een waarde heeft toon dan deze titel inclusief html."

...
<!-- TMPL_IF NAME="titel" -->
  <span id="pagetitle"><!-- TMPL_VAR NAME="titel" --></span>
<!-- /TMPL_IF -->
...

NB: Een TMPL_IF moet altijd worden afgesloten met een /TMPL_IF (TMPL_IF met een / er voor.) 

Als de titel geen waarde heeft, dan wordt er niets van bovenstaande getoond; zowel de TMPL_IF-tags als de html-code waar ze omheen staan verdwijnen uit de html.

Als de variabele geen waarde heeft kan er voor gekozen worden een alternatief te laten zien: "Als de variabele titel een waarde heeft toon dan deze titel, anders toon een standaard tekst."

...
<!-- TMPL_IF NAME="titel" -->
  <span id="pagetitle"><!-- TMPL_VAR NAME="titel" --></span>
<!-- TMPL_ELSE -->
  <span id="pagetitle">Welkom op deze pagina</span>
<!-- /TMPL_IF -->
...

De html-code na de TMPL_ELSE wordt getoond als er geen titel is. Is er wel een titel, dan wordt de html-code boven de TMPL_ELSE getoond. 

Het omgekeerde is ook mogelijk met een TMPL_UNLESS: "Tenzij er een titel is toon een default tekst."

...
<!-- TMPL_UNLESS NAME="titel" -->
  <span id="pagetitle">Welkom op deze pagina</span>
<!-- /TMPL_UNLESS -->
...

NB: een TMPL_UNLESS moet altijd worden afgesloten met een /TMPL_UNLESS (TMPL_UNLESS met een / er voor.)

De standaard titel wordt nu dus alleen getoond als er geen titel is.

Een TMPL_UNLESS kan ook worden gecombineerd met een TMPL_ELSE:

...
<!-- TMPL_UNLESS NAME="titel" -->
  <span id="pagetitle">Welkom op deze pagina</span>
<!-- TMPL_ELSE -->
  <span id="pagetitle"><!-- TMPL_VAR NAME="titel" --></span>
<!-- /TMPL_UNLESS -->
...

Testen op de inhoud van een variabele

In bovenstaande voorbeelden wordt alleen gekeken of de variabele een waarde heeft. Zolang de waarde niet 0 of een lege string '' is heeft de variabele een waarde. Het kan soms handig/nodig zijn om op de keuze te laten afhangen van de exacte waarde van de variabele.

Bijvoorbeeld: als bezoekers zich aanmelden via de nieuwsbriefmodule, dan kunnen ze de aanhef (Dhr. of Mevr.) kiezen. Deze aanhef wordt opgeslagen als M (voor Male) en F (voor Female.) Om de aanhef nu goed te kunnen gebruiken in een nieuwsbrief moeten we niet alleen weten of de variabele 'sex' gevuld is, maar ook welke waarde hij heeft. Dit doen we door middel van het IS attribuut. Is de inhoud van de variabele gelijk aan de inhoud van het IS attribuut, dan is de conditie 'waar':

...
<!-- TMPL_IF NAME="sex" IS="M" -->
Geachte heer,
<!-- TMPL_ELSE -->
  <!-- TMPL_IF NAME="sex" IS="F" -->
   Geachte mevrouw,
  <!-- TMPL_ELSE -->
   L.S.,
  <!-- /TMPL_IF -->
<!-- /TMPL_IF -->
...

Behalve op de letterlijke inhoud kan ook vergeleken/gezocht worden met een reguliere expressie. Een reguliere expressie (afgekort tot "regexp", "regex" of "RE") is een manier om patronen te beschrijven waarmee een computer tekst kan herkennen. Meer over reguliere expressies.

Om bijvoorbeeld te testen of een veld bepaalde woorden bevat kan een reguliere expressie worden gebruikt:

...
<!-- TMPL_IF NAME="Opmerking" RE="ab?cd" -->
Het veld 'Opmerking' bevat de tekst abcd of acd.
<!-- /TMPL_IF -->
...

NB: normaliter wordt een reguliere expressies omsloten door forward-slashes (/), bijv. /ab?cd/. Bij het gebruik in een TMPL_IF is dat niet nodig. /ab?cd/ wordt dus RE="ab?cd".

Voor getallen kan met COMPARE worden bepaald of het getal 'groter', 'groter gelijk aan', 'kleiner' of 'kleiner gelijk aan' een vast getal is ('gelijk kan' kan worden bepaald via de IS="..." constructie).

Getal is kleiner dan 100... lt staat voor 'less than'
<!-- TMPL_IF NAME="Aantal" COMPARE="lt 100" -->
...

Getal is kleiner dan of gelijk aan 100... lte staat voor 'less than or equal'
<!-- TMPL_IF NAME="Aantal" COMPARE="lte 100" -->
...

Getal is groter dan 100... gt staat voor 'greater than'
<!-- TMPL_IF NAME="Aantal" COMPARE="gt 100" -->
...

Getal is groter dan of gelijk aan 100... gte staat voor 'greater than or equal'
<!-- TMPL_IF NAME="Aantal" COMPARE="gte 100" -->
...

De vergelijking kan ook worden gedaan op basis van een andere variabele beschikbaar in het template. Neem in dat geval de naam van de variabele op tussen accolades {...}. Voorbeeld:

Als de prijs_verkoop groter is dan de consumentenprijs dan...
<!-- TMPL_IF NAME="prijs_verkoop" COMPARE="gt {consumentenprijs}" -->
...

Complexe constructies 

Het is toegestaan 1 of meerdere TMPL_IF's of TMPL_UNLESS's in een andere TMPL_IF of TMPL_UNLESS te zetten. Op die manier kunnen complexe constructies worden gebruikt als:

...
<!-- TMPL_IF NAME="nextlevel" -->
  <!-- TMPL_UNLESS NAME="titel" -->
    <span id="pagetitle">Welkom op deze pagina</span>
  <!-- TMPL_ELSE -->
    <span id="pagetitle"><!-- TMPL_IF NAME="leadimage" --><img src="/<!-- TMPL_VAR NAME="leadimg" -->" alt="" /><!-- /TMPL_IF --><!-- TMPL_VAR NAME="titel" --></span>
  <!-- /TMPL_UNLESS -->
<!-- /TMPL_IF -->

Wat staat voor:  "Als er een submenu is (nextlevel heeft een waarde), toont dan iets van een titel: Als er geen titel is, toon dan een standaard tekst, is er wel een titel toon deze dan met een leadimage als deze er is, anders laat de afbeelding weg."

TMPL_INCLUDE

Als een vormgeving uit meerdere html-bestanden bestaat, dan is het mogelijk om de onderdelen die gelijk zijn (bijv. een header of footer) in aparte bestanden te plaatsen. Deze onderdelen kunnen dan met de TMPL_INCLUDE in de html-bestanden worden ingevoegd.

Voorbeeld: de footer is voor alle html-bestanden gelijk, deze staat in een apart bestand genaamd footer.html (de naam van het te 'includen' bestand mag vrij gekozen worden.)

footer.html:

<div id="footer">
© 2003-<!-- TMPL_VAR NAME="year" --> Bedrijfsnaam B.V.
</div>

De footer wordt nu in elk html-bestand als volgt ingevoegd:

...
<!-- TMPL_INCLUDE NAME="footer.html" --> 
...

In de in te voegen bestanden mogen zelf ook weer TMPL_VAR, TMPL_IF en TMPL_UNLESS tags worden gebruikt met dezelfde variabelen als het bestand waarin ze worden ingevoegd. De standaard variabelen zijn dus beschikbaar, maar ook variabelen van modules, eigen stijl-variabelen die bij de configuratie van het html-bestand opgegeven zijn, etc.

Templates delen

Via TMPL_INCLUDE is het ook mogelijk een template te delen met een andere vormgeving. Stel in vormgeving 'abc' staat een template voor de shop: shop_list.html. Die template komt ook van pas voor vormgeving 'xyz' (die met eigen css er voor zorgt dat de weergave toch uniek is).

Door bij vormgeving 'xyz' de template shop_list.html aan te maken met de volgende inhoud

<!-- TMPL_INCLUDE NAME="../abc/shop_list.html" -->

zal het cms de template van 'abc' opnemen in de template van vormgeving 'xyz'. Als de template bij 'abc' wordt aangepast is hij ook meteen aangepast voor 'xyz'. Voor en/of na de TMPL_INCLUDE mag gerust html staan die specifiek voor vormgeving 'xyz' nodig is.

NB: in bovenstaande voorbeeld heten beide templates shop_list.html omdat de shop-module die naam vereist. Maar het is uiteraard geen vereiste dat de namen van templates die ge-include worden hetzelfde moeten zijn (zie ook voorbeeld hieronder).

Een TMPL_INCLUDE mag meerdere keren voor komen in een template. Met onderstaande wordt bijv. een template opgebouwd uit 2 andere:

<h1>Titel van mijn template</h1>
<!-- TMPL_INCLUDE NAME="kop.html" -->
Hieronder volgt een overzicht van producten:
<!-- TMPL_INCLUDE NAME="../vormgeving-y/template-b.html" -->
<!-- TMPL_INCLUDE NAME="../vormgeving-z/footer.html" -->

NB: bedenk dat vele includes (zeker van andere vormgevingen) een template onoverzichtelijk kunnen maken. En als een vormgeving wordt verwijderd zijn die templates ook niet meer beschikbaar voor een andere vormgeving! Onbewust en onbedoeld kan het dan gebeuren dat de andere vormgeving opeens niet meer goed werkt.

Een TMPL_INCLUDE kan ook worden gecombineerd met een TRANSFORM met een replace om bijv. via een <!-- LOOP ... --> constructie een template te kunnen invoegen. Stel je hebt een complex html-blok dat meer dan eens moet worden ingevoegd. In de stijl-variabelen heb je iets staan als

[LOOP 5]
Titel:tmplTitel@@
...
[/LOOP]

In een html template wil je nu een ander template includen waarin je tmplTitel@@ hebt staan. Bijvoorbeeld blok.html met

...
<h2><!-- TMPL_VAR NAME="tmplTitel@@" --></h2>
...

Zonder een TRANSFORM met een replace kun je dat template niet gebruiken omdat de @@ blijven staan na de include. Met onderstaande constructie kun je dat oplossen:

<!-- LOOP 5 -->
<!-- TMPL_INCLUDE NAME="blok.html" TRANSFORM="replace: (?g)\@\@ @@" -->
<!-- /LOOP -->

Het cms zorgt er nu voor dat de inhoud van blok.html 5 keer wordt opgenomen in het template waarbij elke @@ in blok.html wordt vervangen met het juiste nummer van de LOOP.

TMPL_LOOP

Via TMPL_LOOP kunnen alle elementen van een array verwerkt worden (zie stijl-variabelen 'imgarray' en 'docarray').

Voorbeeld:

...
<script type="text/javascript">
  var galleryArray = [];
  <!-- TMPL_LOOP NAME="_xcms_img_array_tmplGallery" -->
  galleryArray.push(['<!-- TMPL_VAR NAME="xcms_url" -->', '<!-- TMPL_VAR NAME="alt" -->']); 
  <!-- /TMPL_LOOP -->
</script>
...

Als de gekozen map bijv. 3 afbeeldingen bevat, dan is het resultaat in de html:

...
<script type="text/javascript">
  var galleryArray = [];
  galleryArray.push(['site/images/map/afbeelding1.gif', 'Alternatieve tekst 1']); 
  galleryArray.push(['site/images/map/afbeelding2.jpg', 'Alternatieve tekst 2']); 
  galleryArray.push(['site/images/map/afbeelding3.gif', 'Alternatieve tekst 3']); 
</script>
...

In een TMPL_LOOP-lus mogen alle voorgenoemde TMPL_... constructies worden gebruikt.

Naast de variabelen per array-element op basis van het type (bijv. document of afbeelding) zijn ook de volgende speciale variabelen beschikbaar per element: