Template is a template compiler and rendering engine. It looks for templates via the pattern apps/{app}/views/{file}.html where the template is passed as 'app/file'. Failing that, it looks for layouts/{file}.html and finally layouts/default.html. It then creates a PHP version of the template and caches it to cache/{app}-{template}.php, so the cache folder must be writeable. Auto-refreshes cached versions when the originals change.

As a result, templates can include any PHP, along with tags of the form:

{{ body }}

And blocks of the form:

{% foreach pages %}
    {{ loop_index }} - {{ loop_value }}
{% end %}

{% if some_val %}
    {{ some_val }}
{% end %}

Note the use of loop_index and loop_value, which are defined for you inside foreach loops by the template engine, or you can specify your own key and value names:

{% for pages as key, page %}
    {{ key }} - {{ page }}
{% end %}

You can also test for more complex conditions, for example:

{% if ! some_val %}
    No value.
{% end %}

{% if some_val == 'some value' %}
    Value: {{ some_val }}
{% end %}

Note that endif and endforeach are valid as well as end, if you prefer, for the sake of clarity.

Here's one more example of how to loop through an array of arrays:

{% foreach my_list %}
    {% foreach loop_value %}
        {{ loop_index }}. {{ loop_value }}<br />
    {% end %}
{% end %}

To break up your template into smaller parts, you can use the inc tag to include one template from inside another. For example:

{% inc header %}

This will include the contents of layouts/header.html into the current template, with the same data passed to it as the main template file.

You can also specify subfolders in this way, to better organize your templates into themes. If you have a theme named layouts/mytheme then you can include a header.html template within it via:

{% inc mytheme/header %}

Note that this will first look for apps/mytheme/views/header.html, which would be the most frequently desired behaviour, and second it will look for layouts/mytheme/header.html, so be sure to name your themes with unique names that do not conflict with the names of apps.

Usage in PHP

To call a template, use:

<?php

echo $tpl->render ('base', array ('foo' => 'bar'));

?>

Note that arrays passed to templates are converted to objects, and objects are left as-is.

Globals

In addition to the fields in the data array passed to render(), you can also call global objects and class methods as follows from within if and foreach blocks as well as variable substitutions:

Call User::constant_value:

{{ User::constant_value }}

Call $GLOBALS['user']->name:

{{ user.name }}

Call a function:

{{ DB::shift ('select * from foo') }}

In an if block:

{% if User::is_valid () %}

{% if user.name != '' %}

In a foreach:

{% foreach Object::some_method () %}

Calling a superglobal:

{{ $_POST.value }}

Note that these must come at the beginning of a statement, not anywhere else within it. The replacement mechanism is very simplistic.

Embedding handlers

You can use special {! app/handler !} tags to embed handlers directly into your templates. These are the equivalent of calling:

{{ controller.run ('app/handler') }}

You can also pass them an array of data using a shorthand like a url:

{! app/handler?param=value&another=value2 !}

Or you can precompile them once when the template is compiled so the output of the handler is hard-coded into the template at compile time like this:

{# app/handler?param=value #}

Filters

Filtering is supported, and htmlspecialchars() is the default filter unless another is specified or 'none' is supplied via:

{{ body|none }}

Any valid function can be a filter, and filters can be chained, executing in the following order:

{{ body|strtoupper|strtolower }}

This evaluates to:

<?php echo strtolower (strtoupper ($data->body)); ?>

You can also set additional parameters to a filter as follows:

{{ timestamp|date ('F j', %s) }}

Built-in filters include:

• quotes - Escape quotes as HTML entities for form input values. See Template::quotes().
• sanitize - Sanitize output against XSS. See Template::sanitize().
• autolink - Replace links in text with HTML links. See Template::autolink().
• absolutize - Ensure a URL value is absolute. See Template::absolutize().
• comma - Outputs the value followed by a comma only if the value is not empty.

String translations

You can use the following tag format to mark strings for translation into the current visitor's language:

{" Text here "}

This will be replaced with a call to:

__ ('Text here')

interface AbstractController {
    public function run ($uri, $data = array ());
}

{{ some_var }}

{{ some_var }}                          # defaults to Template::sanitize()
{{ some_var|none }}                     # no filter
{{ some_var|strtoupper }}               # filters are php functions
{{ some_var|strrev|strtolower }}            # filters can be chained
{{ some_var|my_function }}              # calling a custom function
{{ some_var|date (%s, "F j, Y") }}      # use %s for multiple-parameter functions

{" some text here "}
{' some text here '}

<a href="/example" {{ some_var }}>click me</a>

<a href="/example" id="{{ some_var }}">click me</a>

<span id="some-var">{{ some_var }}</span>

{{ text|quotes }}

<a href="{{ item->photo|absolutize }}">{{item->name}}</a>

{{ text|autolink }}

{{ text|sanitize|autolink }}

{{ text|sanitize|autolink|nl2br }}

{% foreach some_list %}
{% endforeach %}

{% foreach some_list as key, item %}
{% endforeach %}

{% for some_list %}
{% endfor %}

{% for some_list as item %}
{% endfor %}

{% if statement %}
{% elseif statement %}
{% else %}
{% endif %}