Library
The Stamp Template Engine PHP Web Library is a string based, logic-less template engine.
This means 100% separation between PHP and HTML. Stamp is often
used for complex server rendered views.
Working with StampTE is like playing with a paper model, cut out parts and glue them together
(a Stamp is also an appropriate metaphor, hence the name).
Start!
This is how you make a price list for an Italian restaurant using StampTE:
Template:
<table>
<thead>
<tr><th>Pizza</th><th>Price</th></tr>
</thead>
<tbody>
<!-- cut:pizza -->
<tr><td>
#name#
</td><td>
#price#
</td></tr>
<!-- /cut:pizza -->
</tbody>
</table>
Let's add some data:
$data = array(
'Margherita' => '7.00',
'Funghi' => '7.50',
'Tonno' => '8.00'
);
The PHP logic:
$htmlDocument = StampTE::createHtml5Utf8Document();
$htmlDocument->setTitle('Pizza');
$priceList = new StampTE($template);
foreach($data as $name=>$price) {
$pizza = $priceList->getPizza();
$pizza->setName($name);
$pizza->setPrice($price);
$priceList->add($pizza);
}
$htmlDocument->body->add($priceList);
The resulting HTML:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Pizza</title>
</head>
<body>
<table>
<thead><tr><th>Pizza</th><th>Price</th></tr></thead>
<tbody>
<tr><td>Magaritha</td><td>7.00</td></tr>
<tr><td>Funghi</td><td>7.50</td></tr>
<tr><td>Tonno</td><td>8.00</td></tr>
</tbody>
</table>
</body>
</html>
As you can see in the HTML output above the createHtml5Utf8Document() convenience method creates a valid HTML5 document skeleton for you. We then create a price list from the template string. The resulting output looks like this:
| Pizza | Price |
|---|---|
| Margherita | 7.00 |
| Funghi | 7.50 |
| Tonno | 8.00 |
How?
It's easy to see how this template engine works by just reading the example. StampTE simply converts the regions marked in the template to objects you can manipulate. It cuts out the regions and you can then reshuffle them in your HTML.
Syntax
Stamp uses markers, HTML comments. These markers are used to identify regions in the HTML template. Most template engineers already use such markers for readability. Templates become self-documenting and more readable.
StampTE Automatically escapes strings for unicode (X)HTML documents. So no longer have to worry about XSS!
The idea behind StampTE is to cut out pieces, optionally copy them, and glue them elsewhere in the template. StampTE is typically used for complex server rendered views.
Cut
A cut point marks a region in the template that will be cut out from the template
and stored under the specified ID.
This is an example of a template with a cut point marker.
<div>
<!-- cut:diamond -->
<img src="diamond.gif" />
<!-- /cut:diamond -->
</div>
Here we mark an image of a diamond with a cut point marker. We pass the template to Stamp:
$se = new StampTE($templateHTML);
If we now echo $se we see:
<div></div>
To obtain the diamond image we use:
echo $se->getDiamond();
result:
<img src="diamond.gif" />
Glue
A glue point is the opposite of a cut point.
It marks a region where HTML parts can be pasted.
<div>
<!-- cut:diamond -->
<img src="diamond.gif" />
<!-- /cut:diamond -->
</div>
<div id="box">
<!-- paste:jewellery -->
</div>
To drag the diamond in the jewellery box we do:
$diamondOrig = $se->getDiamond();
//copy if you intend to use multiple times...
$diamond = $diamondOrig->copy();
$se->jewellery->add($diamond);
echo $se;
output:
<div id="box">
<img src="diamond.gif" />
</div>
You can add a comma separated list of IDs to restrict the glue point to certain HTML snippets only:
<!-- paste:jewellery(diamond,gem)-->
This glue point only accepts diamonds and gems.
Too many Conditions might slow your website or webapp down. If you intend to use them frequently, consider crafting a little script to remove them before deployment on a production server.
In-place
It's not always necessary to specify a glue point. If the glue point is at the same place as the cutpoint you do not have to use a glue marker. Let's take a look at the following example:
$t = '<box><!-- cut:candy --><candy><!-- /cut:candy --></box>';
$s = new StampTE( $t );
$c = $s->getCandy();
$s->add($c);
$c = $s->getCandy();
$s->add($c);
Result:
<box><candy><candy></box>
This is just a convenience feature of course. You may restrict yourself to precise glue points if you prefer.
Slot
A slot marker can be used to inject strings safely in the template:
<!-- cut:diamond -->
<img src="#picture#" />
<!-- /cut:diamond -->
We can use the slot marker to inject a filename in this case:
$diamond->setPicture('diamond.gif');
Or, if you don't like magic:
$diamond->inject('picture','diamond.gif');
Result:
<img src="diamond.gif" />
String injections are escaped using
htmlspecialchars with ENT_QUOTES for UTF-8 encoding.
Make sure your template uses UTF-8 encoding for optimal security.
If in doubt I recommend
to use the StampTE::createHtml5Utf8Document() method to create the document template for you.
Do NOT use other document encodings unless you know what you are doing!.
Learn more about XSS (pdf).
By default StampTE leaves the slots in the HTML even if they aren't filled. This way
you can easily spot omissions.
If you want a slot to dissapear if it's not filled use:
<input type="checkbox" #checked?# />
Appending your slot with a ? question mark will make the slot 'optional' and therefore remove it from the template string if left empty (requires StampTE 2.0.5+).
Sometimes you want to show some placeholder text in your template, therefore StampTE also supports this version of the slot marker:
<p>
<!-- slot:copyright -->
Copyright © 2013
<!-- /slot:copyright -->
</p>
To fill this slot:
$templ->setCopyright('copyright blah blah...');
Result:
<p>copyright blah blah...</p>
This can be used to show place holder texts to customers and the development team to give them a good idea how the template looks when content has been added.
Here are some examples how to use inject and injectAll. Please do NOT set the escaping option to false (2nd example) unless you really know what you are doing!
//escapes for UTF8 encoding and double quotes
$stamp->inject('imgsrc',$userUrl);
//no escaping be careful!
$stamp->inject('textarea',$userInp,true);
//same as above,alias
$stamp->injectRaw('textarea',$userInp);
//multiple injections
$stamp->injectAll($slots,$raw);
Copy
It's often necessary to copy HTML snippets because you want to inject a different text in each snippet. Copying a Stamp template piece is easy:
$se = new StampTE($templateHTML);
$margherita = $se->getPizza();
$tonno = $margherita->copy();
Here we create a copy of the Pizza Margherita and add tuna to it:
$tonno->add($tuna);
This does not affect the Margherita.
Alternative API:
Instead of getDiamond(), you may use: get('diamond').
Instead of add() you may use glue('jewellery',$diamond).