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.


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>
        <title>My Webpage</title>
        <ul id="navigation">
            <li t:for="item in navigation">
                <a href="{{ item.href }}">{{ item.caption }}</a>

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


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


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

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


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 }}

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


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


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


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


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 }},


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:

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

The if attribute can be used to test an expression:

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

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


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

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.

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.

If not needed, you can omit the condition instruction.

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

To remove an attribute:

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


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.


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>
    <head t:block="head">
        <link rel="stylesheet" href="style.css" />
        <title t:block="title">My Webpage</title>
        <div id="content" t:block="content">
        <div id="footer" t:block="footer">
            &copy; Copyright 2011 by <a href="http://domain.invalid/">you</a>.

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; }

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


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() }}


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


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


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


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.


Pay attention to HTML/XML escaping rules (eg: &lt; 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>

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

Twital behaves the same as Twig in whitespaces handling.


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