Templates

Inleiding

In dit document wordt de werking uitgelegd van de door GiPLan gebruikte templates. Deze templates bieden een manier om het uiterlijk en de data van elkaar te scheiden. Het uiterlijk is dit geval de output zoals deze naar de browser van de gebruiker wordt gestuurd. Dit is met name HTML, aangevuld met CSS (Cascading Style Sheets) en JavaScript. De data wordt aangeleverd door middel van achterliggende PHP-scripts.

Op deze manier kan er afzonderlijk gewerkt worden aan het uiterlijk en de inhoud. De lay-out kan dus verzorgd worden door een specialist op dit gebied, terwijl een PHP-programmeur de data kan verzorgen en zorgt dat de template goed wordt ingevuld en gebruikt.

Er zijn verschillende manieren om dit in feite algemene concept uit te voeren. In dit document maken we gebruik van XTemplates. Deze techniek is terug te vinden op http://sourceforge.net/projects/xtpl.

Vereisten

Software

De daadwerkelijke template-engine bestaat uit 1 bestand, standaard met de naam xtpl.p. Het betreft hier een PHP-script. De engine is getest met PHP versies 3.0.11 en 4.0.4pl1. Er is een web-server nodig met daarop de mogelijkheid om PHP scripts uit te voeren. PHP moet een versie hebben gelijk of hoger aan de hierboven genoemde versies.

Om de geproduceerde pagina's te kunnen testen moet er uiteraard ook een internet-browser beschikbaar. De bekendste zijn Internet Explorer en Netscape.

Tenslotte is er een tekst-editor nodig om de PHP en template bestanden te bewerken. Hulpmiddelen zoals syntax-highlighting en zoek-en-vervang opties zijn hierbij vaak erg handig. Een handige editor is UltraEdit. Op de UltraEdit site zijn ook speciale highlight bestanden te vinden voor PHP en HTML zodat de code duidelijk wordt weergegeven. Dit verhoogt de leesbaarheid enorm en verminderd het aantal syntaxfouten.

Normaal gesproken wordt de HTML vaak geconstrueerd met WYSIWYG applicaties zoals FrontPage en Dreamweaver, maar aangezien er nu in de template bestanden gebruik gemaakt moet worden van speciale taal constructies die niet bekend zijn bij deze programma's is dat in dit geval niet handig. Wel kunnen deze programma's gebruikt worden om het uiterlijk vorm te geven, waarna met behulp van een tekst-editor de template specifieke elementen kunnen worden aangepast.

Kennis

Om goed met deze templates te kunnen werken zijn er 3 vaardigheden vereist. Allereerst is er een basis kennis nodig van PHP. PHP lijkt qua syntax erg veel op de programmeertaal C en is uitgebreid gedocumenteerd. De online documentatie is te vinden op www.php.net/manual. Deze is tevens voorzien van commentaar van gebruikers wat regelmatig zeer handig is.
In dit document zal er niet diep worden ingegaan op de werking van PHP omdat dit buiten de scope van dit document valt.

Ten tweede moet er een algemene kennis zijn van HTML om de uiteindelijke output naar de browser te kunnen verzorgen. HTML is in principe een simpele opmaak-taal waar online enorm veel informatie over te vinden is. Een goede nederlandstalige site hierover is Handleiding HTML.
Er kan hierbij tevens nog gebruikt gemaakt worden van geavanceerdere technieken zoals CSS en JavaScript, maar dit is niet noodzakelijk voor de goede werking van de templates.

Tenslotte is er een basis kennis nodig van de gebruikte templates. Deze wordt besproken in de rest van dit document.

De algemene werking

We zullen nu een kort voorbeeld uitwerken om de initialisatie en algemene werking van de templates te demonstreren. In dit voorbeeld maken we een simpele template pagina aan waarop we de huidige tijd weergeven (3 keer).

Initialisatie

Om te kunnen werken met de templates moet eerst de template-engine worden geinitialiseerd. Maak hiervoor een leeg tekstbestand aan en sla het op als test.php. Van belang is hierbij vooral de .php extensie. Deze is noodzakelijk om het bestand goed weergegeven te laten worden door de webserver (uitgaande van de normale gangbare instellingen).

Bewerk nu dat bestand met de gekozen tekst-editor en zet er de volgende code in:

<?

// lees de template-engine code in
// zorg ervoor dat het xtpl.p bestand ook op de aangewezen plek te vinden is
include("xtpl.p");

// template aanmaken (xtpl.p maakt gebruikt van het klassen systeem in PHP, 
// voor meer info www.php.net/manual/en/language.oop.php)
$xtpl = new XTemplate ("test.tpl");

In dit stuk code wordt de template-engine geinitaliseerd en wordt het template bestand test.tpl ingeladen. Dit bestand zullen we straks aanmaken, maar we concentreren ons eerst op de rest van test.php.

Invulling inhoud

In test.php hebben we nu de template-engine aangemaakt en er is de link gemaakt met test.tpl. Nu is het de bedoeling om de inhoud vanuit test.php in de template (test.tpl) te krijgen.
Dit gebeurd met de functies assign en parse.
Met assign kan er een waarde worden toegekend aan een variabele binnen het template bestand. Wanneer er binnen het template bestand een variabele gebruikt wordt door middel van het invoegen van {variabele_naam} kan de programmeur hier een waarde aan toekennen met de volgende code:
$xtpl -> assign("variabele_naam","waarde van de variabele, kan van alles zijn");
Uiteindelijk ziet de gebruiker dan dus niet {variabele_naam} in zijn browser verschijnen, maar de tekst waarde van de variabele, kan van alles zijn.
De waarde die toegekend wordt aan de variabele kan zowel een string of een getal zijn.

De andere functie, parse, stuurt een blok template code in een keer naar de browser. Op deze manier kan er code worden hergebruikt en gestructureerd.
Wanneer er binnen een template bestand een blok wordt neergezet kan dit blok vanuit het PHP bestand willekeurig vaak worden weergegeven met behulp van de functie parse.
Het blok wordt als volgt in het template bestand gezet:

<!-- BEGIN: blok1 -->
Dit is een blok<br>
<!-- END: blok1 -->
Dit blok kan men weergeven door de volgende regel code op te nemen in het PHP bestand.
$xtpl -> parse("blok1");
Om het systeem nog krachtiger te maken, kunnen blokken ook worden genest. Het lastige is hierbij dat de nesting van het blok moet worden aangegeven binnen het parse commando, maar dit komt terug in het volgende stuk code. Het is van belang op te merken dat er altijd een alles omvattend blok moet zijn, meestal main geheten, waarin alle andere variabelen en blokken zijn bevat (vergelijkbaar met XML, waar ook altijd een root-element moet bestaan).

We gaan nu het template bestand aanmaken waarin we de tijd gaan weergeven.
Maak een leeg tekstbestand aan en sla het op als test.tpl. Zet hier vervolgens de volgende code in:

<!-- BEGIN: main -->
<html>
	<head>
	<title>Tijd test</title>
	</head>
	
	<body>
	<h1>De tijd</h1>
	
	<!-- BEGIN: tijd -->
	De huidige tijd is: {tijd}<br>
	<!-- END: tijd -->
	
	</body>
</html>
<!-- END: main -->
We maken hier een alles omvattend blok main met daarin HTML code en een blok tijd met daarin de variabele {tijd}.

Met de volgende code, die in het PHP bestand (test.php) gezet moet worden, zorgen we er nu voor dat het blok tijd 3 keer ge-parse-d wordt, waarbij de variabele {tijd} de waarde krijgt van (een representatie van) de huidige tijd.

// geef de variabele tijd de goede waarde
// hier wordt gebruik gemaakt van de functies strftime en time, 
// dat is verder van ondergeschikt belang
$xtpl->assign("tijd",strftime("%R",time());

// parseer het blok tijd 3 maal
// let hierbij op de aanpassing van de functieaanroep naar aanleiding van de nesting
$xtpl->parse("main.tijd");
$xtpl->parse("main.tijd");
$xtpl->parse("main.tijd");
Het is van belang om eerst de variabele een naam te geven, en daarna pas het blok waarin deze variabele staat te parseren. Een omgekeerde volgorde zal een ongewenst effect geven.
Omdat de variabele tijd hier steeds dezelfde waarde heeft (uitvoering van het script gaat binnen eem seconde, dus de tijd veranderd niet) hoeft deze maar 1 keer toegewezen te worden aan {tijd}.

Afsluiten

Wanneer er op deze manier verschillende variabelen zijn ge-assign-ed en blokken zijn ge-parse-d is het nog zaak om het eindresultaat naar de browser te sturen. Hierbij komt het eerder genoemde alles omvattende blok naar voren. Dit moet hier namelijk nog ge-parse-d worden wanneer dit nog niet is gebeurd en tenslotte moet het resultaat naar de browser worden gestuurd.
Dit gebeurd door de volgende code aan het eind van het PHP bestand te plaatsen.
$xtpl->parse("main");

// stuur het eindresultaat naar de browser
$xtpl->out("main");
?>
Wanneer nu de bestanden test.php, test.tpl en xtpl.p in een directory worden gezet welke bereikbaar is via de webserver kan het resultaat bekeken worden.
De complete inhoud van test.php en test.tpl kan hier worden bekeken.

Voorbeelden

In dit onderdeel geven we enkele voorbeelden van het gebruik van de templates.

Variabelen

Variabelen kunnen zoals reeds gezegd werd gebruikt worden door middel van de volgende code:

In de template:

{variabele}
In het PHP bestand:
$xtpl->assign("variabele","waarde van de variabele");

Ook is het mogelijk in de template direct de elementen van een array te gebruiken. Op deze manier hoef je alleen de array te assignen en zijn alle variabelen in deze array automatisch beschikbaar.
In de template:

<h1>Gebruiker:</h1>
{gebruiker.naam}<br>
{gebruiker.email}<br>
{gebruiker.leeftijd}<br>
In het PHP bestand:
// de array initialiseren
$gebruiker = array();
$gebruiker['naam'] = "Jan Janssen";
$gebruiker['email'] = "j.janssen@provider.com";
$gebruiker['leeftijd'] = "28";

$xtpl->assign("gebruiker",$gebruiker);

Binnen de template-engine zijn standaard de globale variabele binnen het script ook beschikbaar. In het volgende voorbeeld is zichtbaar hoe de PHP_SELF variabele, waarin de naam van het huidige script te vinden is, wordt gebruikt in een template. Hiervoor hoeft niets te veranderen in het PHP bestand. In de template:

{PHP.PHP_SELF}
Door het PHP. gedeelte weet de template-engine dat hier een globale variabele moet worden ingevuld.

Blokken

Blokken zijn in feite het krachtigste element van de templates. Op deze manier kunnen stukken code eenvoudig worden hergebruikt.
In het volgende voorbeeld laten we een eenvoudige tabel naar de browser sturen. In de template:

<!-- BEGIN: tabel -->
<table border="1">
	<tr>
		<td>Dit is de bovenste 'header' rij</td>
	</tr>
	<!-- BEGIN: rij -->
	<tr>	
		<td>Inhoud van deze cel: {var}</td>
	</tr>
	<!-- END: rij -->
</table>
<!-- END: tabel -->
In het PHP bestand:
//geef var een waarde en parseer een rij
$xtpl->assign("var","cel 1");
$xtpl->parse("main.tabel.rij");

//geef var een waarde en parseer een rij
$xtpl->assign("var","cel 2");
$xtpl->parse("main.tabel.rij");

//geef var een waarde en parseer een rij
$xtpl->assign("var","cel 3");
$xtpl->parse("main.tabel.rij");

//parseer de hele tabel
$xtpl->parse("main.tabel");

In het PHP bestand gaan we er nu van uit dat dit template gedeelte binnen een omvattend main blok valt (en dan ook nog precies eronder).
Het resultaat zal er als volgt uitzien:
Dit is de bovenste 'header' rij
Inhoud van deze cel: cel 1
Inhoud van deze cel: cel 2
Inhoud van deze cel: cel 3

Bestanden nesten

Het is mogelijk andere template bestanden te gebruiken in je huidige template bestand met de volgende code:
In de template:
{FILE "bestandsnaam.tpl"}
Dit zorgt ervoor dat de gehele inhoud van het bestand bestandsnaam.tpl op die plaats wordt ingevoegd. Dit valt dus binnen de bestaande nesting van de blokken etc.
In het volgende voorbeeld is te zien hoe dit in z'n werk gaat.
In de template test1.tpl:
<h1>{titel}</h1>
<p>{inhoud}</p>

test1.tpl is hier syntaxtisch exact gelijk aan de volgende code:
In de template test2.tpl:

<h1>{titel}</h1>
{FILE "inhoud.tpl"}

In de template inhoud.tpl:
<p>{inhoud}</p>

Het parseren van blokken en toewijzen van variabelen binnen het PHP bestand staat geheel los van deze manier van het nesten van bestanden. Het PHP bestand behandelt de hele template gewoon alsof het 1 groot bestand is waarbij alle geneste bestanden vervangen zijn door de daadwerkelijk inhoud van deze bestanden.

Tenslotte

Het goed leren werken met de templates is vooral een kwestie van veel uitproberen en kijken of het het gewenste resultaat oplevert. Wij hebben er in ieder geval zeer prettige ervaringen mee en we hopen dat dit document wat duidelijkheid verschaft over de werking van XTemplates en templates in het algemeen.

Begrippen

  • Template-engine: de software die ervoor zorgt dat de templates naar behoren werken.
  • PHP: een populaire Webscriptingtaal, te vinden op www.php.net.
  • Webscripting: het programmeren van een dynamische web-pagina.
  • WYSIWYG: What You See Is What You Get, oftewel: zoals het wordt weergegeven op het scherm zal het ook uiteindelijk bij de gebruiker verschijnen.
  • CSS: Cascading Style Sheets, een manier om de layout van een webpagina centraal te bepalen. [Uitleg]
  • JavaScript: een programmeertaal waarmee client-side, dus aan de kant van de gebruiker, dingen mee kunnen worden gedaan. Voorbeelden zijn het controleren en invullen van formulieren en het manipuleren van plaatjes.
  • Template bestand: een bestand met de .tpl extensie (bij voorkeur) met daarin specifieke template constructies.

Gebruikte code

test.php

<?

// lees de template-engine code in
// zorg ervoor dat het xtpl.p bestand ook op de aangewezen plek te vinden is
include("xtpl.p");

// template aanmaken (xtpl.p maakt gebruikt van het klassen systeem in PHP, 
// voor meer info www.php.net/manual/en/language.oop.php)
$xtpl = new XTemplate ("test.tpl");

// geef de variabele tijd de goede waarde
// hier wordt gebruik gemaakt van de functies strftime en time, 
// dat is verder van ondergeschikt belang
$xtpl->assign("tijd",strftime("%R",time());

// parseer het blok tijd 3 maal
// let hierbij op de aanpassing van de functieaanroep naar aanleiding van de nesting
$xtpl->parse("main.tijd");
$xtpl->parse("main.tijd");
$xtpl->parse("main.tijd");

$xtpl->parse("main");

// stuur het eindresultaat naar de browser
$xtpl->out("main");

?>

test.tpl

<!-- BEGIN: main -->
<html>
	<head>
	<title>Tijd test</title>
	</head>
	
	<body>
	<h1>De tijd</h1>
	
	<!-- BEGIN: tijd -->
	De huidige tijd is: {tijd}<br>
	<!-- END: tijd -->
	
	</body>
</html>
<!-- END: main -->