Twital for Template Designers¶

This document gives you an overview on Twital principles: how to write a template and what to bear in mind for making it work well.

Introduction¶

A template is simply a text file. Twital can generate any HTML/XML format.

To make it work, your templates must match the configured file extension.

By default, Twital compiles only templates whose name ends with .twital.xml, .twital.html, .twital.xhtml (using respectively XML, HTML5 and XHTML rules to format the output).

A Twital template is basically a Twig template that takes advantage of the natural HTML/XML tree structure (avoiding redundant control flow instructions). All expressions are completely Twig compatible; control flow structures (Twig calls them tags) are just replaced by some Twital tags or attributes.

Here is a minimal template that illustrates a few basics:

<!DOCTYPE html>
<html>
    <head>
        <title>My Webpage</title>
    </head>
    <body>
        <ul id="navigation">
            <li t:for="item in navigation">
                <a href="{{ item.href }}">{{ item.caption }}</a>
            </li>
        </ul>

        <h1>My Webpage</h1>
        {{ a_variable }}
    </body>
</html>

Tip

See here how to use specific output formats as XML or XHTML and HTML5.

IDEs Integration¶

Any IDE that supports Twig syntax highlighting and auto-completion should be configured to support Twital.

Here you can find a list of IDEs that support Twig/Twital

Variables¶

To print the content of variables, you can use exactly the same Twig syntax, using Twig functions, filters etc.

{{ foo.bar }}
{{ foo['bar'] }}
{{ attribute(foo, 'data-foo') }}

Note

To learn more about Twig variables, you can read the Twig official documentation

Setting Variables¶

The t:set attribute acts in the same way as the Twig’s set tag and allows you to set a variable from a template.

<div t:set="name = 'Tom'">
    Hello {{ tom }}
</div>

<t:omit t:set="numbers = [1,2], items = {'item':'one'}"/>
{# t:omit tag will not be output-ed, but t:set will work #}

Note

To learn more about Twig set, you can read the Twig official documentation

Filters¶

You can use all Twig filters directly into Twital. Here is just an example:

{{ name|striptags|title }}
{{ list|join(', ') }}

You can also use the Twital attribute t:filter to filter the content of an element.

<div t:filter="upper">
    This text becomes uppercase
</div>

Note

To learn more about Twig filters, you can read the Twig official documentation

Functions¶

You can use all Twig functions directly from Twital.

For instance, the range function returns a list containing an arithmetic progression of integers:

<div t:for="i in range(0, 3)">
    {{ i }},
</div>

Note

To learn more about Twig filters, you can read the Twig official documentation

Control Structure¶

Almost all Twig control structures have a Twital equivalent node or attribute.

For example, to display a list of users, provided in a variable called users, use the for attribute:

<h1>Members</h1>
<ul>
    <li t:for="user in users">
        {{ user.username|e }}
    </li>
</ul>

The if attribute can be used to test an expression:

<ul t:if="users|length">
    <li t:for="user in users">
        {{ user.username|e }}
    </li>
</ul>

Go to the tags page to learn more about the built-in attributes and nodes.

To learn more about Twig control structures, you can read the Twig official documentation

Attributes¶

To create HTML/XML attributes, you do not have to mess up HTML tags with control structures. Twital makes things really easy!

Take a look at the following example:

<div t:attr=" condition ? class='header'">
    My Company
</div>

Using the t:attr attribute, you can conditionally add an attribute depending on the value of the condition expression.

You can use any Twig expression as a condition or attribute value. The attribute name must be a literal.

<div t:attr="
    users | length ? class='header'|upper ,
    item in array ? class=item">
    Here wins the last condition, which will be evaluated as true.
</div>

You can also append some content to existing attributes using the t:attr-append.

<div class="row"
    t:attr-append=" i mod 2 ? class=' even'">
     class will be "row even" if 'i' is odd.
</div>

If not needed, you can omit the condition instruction.

<div t:attr="class='row'" t:attr-append=" class=' even'">
     Class will be "row even"
</div>

To remove an attribute:

<div t:attr=" condition ? class=null">
     Class will be "row even"
</div>

Comments¶

To comment-out part of a line in a template, you can use the Twig comment syntax {# ... #}.

Including other Templates¶

The include tag is useful for including a template and returning the rendered content of that template into the current one:

<t:include from="sidebar.html"/>

Inclusions work exactly as in Twig.

Note

To learn more about Twig inclusion techniques, you can read the Twig official documentation

Template Inheritance¶

Twital’s template inheritance is almost identical to Twig. Twital adds just some features useful to define new blocks.

Here we define a base template, base.html, which defines a simple HTML skeleton document that you might use for a simple two-column page:

<!DOCTYPE html>
<html>
    <head t:block="head">
        <link rel="stylesheet" href="style.css" />
        <title t:block="title">My Webpage</title>
    </head>
    <body>
        <div id="content" t:block="content">
        </div>
        <div id="footer" t:block="footer">
            &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.
        </div>
    </body>
</html>

In this example, the t:block attributes define four blocks that child templates can fill in. All the t:block attributes tell the template engine that a child template may override those portions of the template.

A child template might look like this:

<t:extends from="base.html">

    <t:block name="title">Index</t:block>

    <t:block name="head">
        {{ parent() }}
        <style type="text/css">
            .important { color: #336699; }
        </style>
    </t:block>

    <t:block name="content">
        <h1>Index</h1>
        <p class="important">
            Welcome to my awesome homepage.
        </p>
    </t:block>

</t:extends>

The t:extends node tells the template engine that the template “extends” another template. When the template system evaluates the template, it first locates the parent.

The extends tag should be the first tag in the template.

Note that, since the child template does not define the footer block, the value from the parent template is used instead.

To render the contents of the parent block, use the parent Twig function. The following template gives back the results of the parent block:

<t:block name="sidebar">
    <h3>Table Of Contents</h3>
    ...
    {{ parent() }}
</t:block>

Tip

The documentation page for the extends tag describes more advanced features like block nesting, scope, dynamic inheritance, and conditional inheritance.

Note

To learn more about Twig inheritance, you can read the Twig official documentation

Macros¶

Twital also supports Twig macros. A macro is defined via the macro tag.

Note

To learn more about Twig macros, you can read the Twig official documentation

Expressions, Literals and Operators¶

All expressions, literals and operators that can be used with Twig, can also be used with Twital.

Note

Pay attention to HTML/XML escaping rules (eg: < or > inside attributes).

Whitespace Control¶

Twital will try to respect almost all whitespaces that you type. To remove whitespaces between HTML tags, you can use the t:spaceless attribute:

<div t:spaceless="">
    <strong>foo bar</strong>
</div>

{# output will be <div><strong>foo bar</strong></div> #}

Twital behaves the same as Twig in whitespaces handling.

Extensions¶

Twital can be easily extended. To learn how to create your own extension, you can read the Extending Twital chapter.