Advanced

This chapter discusses advanced features of the Stamp Template Engine library.

Path

If you have nested cut point markers in a template you can obtain them like this:



$se->get('path.to.the.treasure');

...finds a treasure in this template:

<!-- cut:path -->
    <!-- cut:to -->
        <!-- cut:the -->
            <!-- cut:treasure -->
                <gold />
            <!-- /cut:treasure -->
        <!-- /cut:the -->
    <!-- /cut:to -->
<!-- /cut:path -->

Translator

To set a translator function:

$stampTE->setTranslator(function($argument1,...){
    return $DICT[$argument1];
});

To invoke the translator, use the magic method 'say' to fill a slot:



$stampTE->sayHello('Hello!');

This will pass the string 'Hello!' to the translator function. Note that the resulting content will still be filtered using the XSS-filter.

Collect

To obtain a lot of elements defined in a template all at once, you can collect them like this:

<!-- cut:chest -->
<div>
    <!-- cut:diamond -->
    <img src="diamond.gif" />
    <!-- /cut:diamond -->
</div>
<!-- /cut:chest -->

<div id="box">
    <!-- paste:jewellery -->
</div>

list($diamond,$chest) =
    $se->collect('chest.diamond|chest');

Cache

StampTE supports a basic caching mechanism. To write something to the cache:



$se->writeToCache('chest.diamond|chest');

To get the cache object:



$cache = $se->getCache();

You can now store the cache on disk and retrieve the serialized blob later to improve performance. The benefit of this approach is that StampTE does not have to perform the regular expressions to cut out the template snippets. To set the cache object:



$se->loadIntoCache($cache);

ID

An HTML snippet is identified by the region ID. For instance the region ID of:

<!-- cut:pizza -->
    <pizza>
        <olive />
    </pizza>
<!-- /cut:pizza -->

is: "pizza" To obtain the ID of our pizza:

$se = new StampTE($templateHTML);
echo $se->get('pizza')->getID(); //outputs 'pizza'

Factory

You can tell StampTE (since 2.0.1) to return something different than a StampTE template. To do so, set a factory closure function like this:

$stampTE->setFactory(function($html,$id){
    if ($id == 'button') {
        return new TextField($html,$id);
    }
    else {
        return new StampTE($html,$id);
    }
 });

I recommend to subclass StampTE:



class TextField extends StampTE { ... }

Now you can add your own methods to a StampTE object:

$t = $s->getTextField();
$t->addAttribute('required');

In this example, the custom TextField object offers an addAttribute method to set an attribute in the HTML.

Attribute

Sometimes you have HTML like this:



$t = '<input type="checkbox" />';

What if you want to set the checked-attribute? Of course you could do something like:



$t = '<input type="checkbox" #checked# />';

However this is not very neat. Some IDEs or editors get confused, it's not valid HTML and it does not render properly. That's why we have certain special slots. They work just like normal slots but they look better if you present the raw template to a customer.



$t = '<input type="checkbox" data-stampte="#state?#" />';

Here you see the special StampTE attribute, called data-stampte. To fill this attribute slot with the value 'checked' write:

$s = new StampTE($t);
$s->injectAttr('state','checked');

This will result in:



<input type="checkbox" checked />

As you can see, the data-stampte attribute will be removed from the resulting string. This works just like a normal slot except that the slot looks different before it has been processed which might make a slightly better impression in your pre-processed HTML document.

Toggle

Instead of using injectAttr() you can also use:

$t = '<input type="checkbox" data-stampte="#checked?#" />';
$s = new StampTE($t);
$s->attr('checked', true);

This will have the same result. In this case the slot will be filled with the value of the name of the slot.

DemoJS

DemoJS is a little Javascript snippet that allows you to clean up templates that will not be processed by PHP. One of the strengths of StampTE is that you can show templates to customers and then implement them without modifying them, however your template may consist of HTML like this:



<img src="#logo#" />

While this is syntactically correct HTML it does not look nice because the logo will not appear. Therefore you can replace slots for demo purposes using the DemoJS script:

<script src="demo.js">
    {
        '#logo#':'demo_logo.jpg',
        '#alt#':'This is a demo alt text!'
    }
</script>

Simply put an object in the script tag with VALUE -> REPLACE pairs, and the DemoJS script will replace the slots for you (requires a modern browser).

Filter

To override the default escaping system simply sublcass and override the filter() method:

class MyFilterStampTE extends StampTE {
    protected function filter($data) {
        return mySpecialEscapeFunction($data);
    }
}