Basics

The idea behind StampTE is to cut out pieces, optionally copy them, and glue them elsewhere in the template.

Installation

Installation is really simple. Just download the tarball, untar and require the library file like this:

    require('StampTE.php');

    use 
StampTemplateEngine\StampTE as StampTE;
    use 
StampTemplateEngine\StampTEException as StampTEException;

Cut Point

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 Point

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 glue

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 Marker

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.

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 &copy2013
        
<!-- /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);

Copying

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).