if
The Twital instruction for Twig’s if tag is the``t:if`` attribute.
<p t:if="online == false">
Our website is in maintenance mode. Please, come back later.
</p>
elseif and else are not well supported, but you can always combine Twital with Twig.
<p t:if="online_users > 0">
{%if online_users == 1%}
one user
{% else %}
{{online_users}} users
{% endif %}
</p>
But if you are really interested to use elseif and else tags with Twital
you can do it anyway.
<p t:if="online">
I'm online
</p>
<p t:elseif="invisible">
I'm invisible
</p>
<p t:else="">
I'm offline
</p>
This syntax will work if there are no non-space charachters between the p tags.
This example will not work:
<p t:if="online">
I'm online
</p>
<hr />
<p t:else="">
I'm offline
</p>
<p t:if="online">
I'm online
</p>
some text...
<p t:else="">
I'm offline
</p>
for
The Twital instruction for Twig’s for tag is the t:for attribute.
Loop over each item in a sequence. For example, to display a list of users
provided in a variable called users:
<h1>Members</h1>
<ul>
<li t:for="user in users">
{{ user.username }}
</li>
</ul>
set
The Twital instruction for Twig set tag is the t:set attribute.
You can use set to assign variables. The syntax to use the set attribute is:
<p t:set=" name = 'tommy' ">Hello {{ name }}</p>
<p t:set=" foo = {'foo': 'bar'} ">Hello {{ foo.bas }}</p>
<p t:set=" name = 'tommy', surname='math' ">
Hello {{ name }} {{ surname }}
</p>
block
The Twital instruction for Twig block tag is t:block node.
To see how to use it, consider the following base template named layout.html.twital:
<html>
<head>
<title>Hello world!</title>
</head>
<body t:block="content">
Hello!
</div>
</html>
To improve the greeting message, we can extend it using the t:textends node,
so we can create a new template called hello.html.twital.
<t:extends from="layout.html.twital">
<t:block name="content">
Hello {{name}}!
</t:block>
</t:extends>
As you can see, we have overwritten the content of the content block with a new one.
To do this, we have used a t:block node.
Of course, if needed, you can also call the parent block from inside. It is simple:
<t:extends from="layout.html.twital">
<t:block name="content">
{{parent()}}
Hello {{name}}!
</t:block>
</t:extends>
extends
The Twital instruction for Twig extends tag is t:extends node.
To see how to use it, take a look at this example:
Consider the following base template named layout.html.twital.
Here we are creating a simple page that says hello to someone.
With the t:block attribute we mark the body content as extensibile.
<html>
<head>
<title>Hello world!</title>
</head>
<body>
<div t:block="content">
Hello!
</div>
</div>
</html>
To improve the greating message, we can extend it using the t:textends node,
so we can create a new template called hello.html.twital.
<t:extends from="layout.html.twital">
<t:block name="content">
Hello {{name}}!
</t:block>
</t:extends>
As you can see, we have overwritten the content of the content block with a new one.
To do this, we have used a t:block node.
You can also extend a Twig Template, so you can mix Twig and Twital Templates.
<t:extends from="layout.twig">
<t:block name="content">
Hello {{name}}!
</t:block>
</t:extends>
Sometimes it’s useful to obtain the layout template name from a variable:
to do this you have to add the Twital namespace to attribute name:
<t:extends t:from="layoutVar">
<t:block name="content">
Hello {{name}}!
</t:block>
</t:extends>
Now hello.html.twital can inherit dynamically from different templates.
Now the tempalte name can be any valid Twig expression.
embed
The Twital instruction for Twig embed tag is t:embed node.
The embed tag combines the behaviour of include and extends.
It allows you to include another template’s contents, just like include does.
But, it also allows you to override any block defined inside the included template,
like when extending a template.
To learn about the usefulness of embed, you can read the official documentation.
Now, let’s see how to use it, take a look to this example:
<t:embed from="teasers_skeleton.html.twital">
<t:block name="left_teaser">
Some content for the left teaser box
</t:block>
<t:block name="right_teaser">
Some content for the right teaser box
</t:block>
<t:embed>
You can add additional variables by passing them after the with attribute:
<t:embed from="header.html" with="{'foo': 'bar'}">
...
</t:embed>
You can disable the access to the current context by using the only attribute:
<t:embed from="header.html" with="{'foo': 'bar'} only="true">
...
</t:embed>
- You can mark an include with
ignore-missing attribute in which case Twital
- will ignore the statement if the template to be included does not exist.
<t:embed from="header.html" with="{'foo': 'bar'} ignore-missing="true">
...
</t:embed>
ignore-missing can not be an expression; it has to be evaluated only at compile time.
To use Twig expressions as template name you have to use a namespace prefix on ‘form’ attribute:
<t:embed t:from="ajax ? 'ajax.html' : 'not_ajax.html' ">
...
</t:embed>
<t:embed t:from="['one.html','two.html']">
...
</t:embed>
include
The include statement includes a template and returns the rendered content
of that file into the current namespace:
<t:include from="header.html"/>
Body
<t:include from="footer.html"/>
A little bit different syntax to include a template can be:
<div class="content" t:include="news.html">
<h1>Fake news content</h1>
<p>Lorem ipsum</p>
</div>
In this case, the content of div will be replaced with the content of template ‘news.html’.
You can add additional variables by passing them after the with attribute:
<t:include from="header.html" with="{'foo': 'bar'}"/>
You can disable the access to the current context by using the only attribute:
<t:include from="header.html" with="{'foo': 'bar'} only="true"/>
- You can mark an include with the
ignore-missing attribute in which case Twital
- will ignore the statement if the template to be included does not exist.
<t:include from="header.html" with="{'foo': 'bar'} ignore-missing="true"/>
ignore-missing can not be an expression; it has to be evauluated only at compile time.
To use Twig expressions as template name you have to use a namespace prefix on ‘form’ attribute:
<t:include t:from="ajax ? 'ajax.html' : 'not_ajax.html' " />
<t:include t:from="['one.html','two.html']" />
import
The Twital instruction for Twig import tag is t:import node.
Since Twig supports putting often used code into macros. These
macros can go into different templates and get imported from there.
There are two ways to import templates: (1) you can import the complete template into a variable or (2)
request specific macros from it.
Imagine that we have a helper module that renders forms (called forms.html):
<t:macro name="input" args="name, value, type">
<input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" />
</t:macro>
<t:macro name="textarea" args="name, value">
<textarea name="{{ name }}">{{ value|e }}</textarea>
</t:macro>
To use your macro, you can do something like this:
<t:import from="forms.html" alias="forms"/>
<dl>
<dt>Username</dt>
<dd>{{ forms.input('username') }}</dd>
<dt>Password</dt>
<dd>{{ forms.input('password', null, 'password') }}</dd>
{{ forms.textarea('comment') }}
</dl>
If you want to import your macros directly into your template (without referring to it with a variable):
<t:import from="forms.html" as="input as input_field, textarea"/>
<dl>
<dt>Username</dt>
<dd>{{ input_field('username') }}</dd>
<dt>Password</dt>
<dd>{{ input_field('password', '', 'password') }}</dd>
</dl>
<p>{{ textarea('comment') }}</p>
Tip
To import macros from the current file, use the special _self variable
for the source.
macro
The Twital instruction for Twig macro tag is t:macro node.
To declare a macro inside Twital, the syntax is:
<t:macro name="input" args="value, type, size">
<input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
</t:macro>
To use a macro inside your Twital template, take a look at the :doc:import<../tags/import> attribute.
use
The Twital instruction for Twig use tag is t:use node.
This is a fature that allows a/the horizontal reuse of templates.
To learn more about it, you can read the official documentation.
Let’s see how does it work:
<t:use from="bars.html"/>
<t:block name="sidebar">
...
</t:block>
You can create some aliases for block inside “used” template to avoid name conflicting:
<t:extends from="layout.html.twig">
<t:use from="bars.html" aliases="sidebar as sidebar_original, footer as old_footer"/>
<t:block name="sidebar">
{{ block('sidebar_original') }}
</t:block>
</t:extends>
sandbox
The Twital instruction for Twig import tag is t:sandbox node or the t:sandbox attribute.
The sandbox tag can be used to enable the sandboxing mode for an included
template, when sandboxing is not enabled globally for the Twig environment:
<t:sandbox>
{% include 'user.html' %}
</t:sandbox>
<div t:sandbox="">
{% include 'user.html' %}
</div>
autoescape
The Twital instruction for Twig autoescape tag is t:autoescape attribute.
Whether automatic escaping is enabled or not, you can mark a section of a
template to be escaped or not by using the autoescape tag.
To see how to use it, take a look at this example:
<div t:autoescape="true">
Everything will be automatically escaped in this block
using the HTML strategy
</div>
<div t:autoescape="html">
Everything will be automatically escaped in this block
using the HTML strategy
</div>
<div t:autoescape="js">
Everything will be automatically escaped in this block
using the js escaping strategy
</div>
<div t:autoescape="false">
Everything will be outputted as is in this block
</div>
When automatic escaping is enabled, everything is escaped by default, except for
values explicitly marked as safe. Those can be marked in the template by using
the Twig raw filter:
<div t:autoescape="false">
{{ safe_value|raw }}
</div>
capture
This attribute acts as a set tag and allows to ‘capture’ chunks of text into a variable:
<div id="pagination" t:capture="foo">
... any content ..
</div>
All contents inside “pagination” div will be captured and saved inside a variable named foo.
filter
The Twital instruction for Twig filter tag is t:filter attribute.
To see how to use it, take a look at this example:
<div t:filter="upper">
This text becomes uppercase
</div>
<div t:filter="upper|escape">
This text becomes uppercase
</div>
spaceless
The Twital instruction for Twig spaceless tag is t:spaceless node or the t:spaceless attribute.
<t:spaceless>
{% include 'user.html' %}
</t:spaceless>
<div t:spaceless="">
{% include 'user.html' %}
</div>
omit
This attribute asks the Twital parser to ignore the elements’ open and close tag,
its content will still be evaluated.
<a href="/private" t:omit="false">
{{ username }}
</a>
<t:omit>
{{ username }}
</t:omit>
This attribute is useful when you want to create element optionally,
e.g. hide a link if certain condition is met.
attr
Twital allows you to create HTML/XML attributes in a very simple way.
You do not have to mess up with control structures inside HTML tags.
Let’s see how does it work:
<div t:attr=" condition ? class='header'">
My Company
</div>
Here we add conditionally an attribute based on the value of the condition expression.
You can use any Twig test expression as condition and attribute value,
but the attribute name must be a litteral.
<div t:attr="
users | length ? class='header'|upper ,
item in array ? class=item">
Here wins the last class that condition will be evaluated to true.
</div>
When not needed, you can omit the condition instruction.
<div t:attr="class='row'">
Class will be "row"
</div>
To set an HTML5 boolean attribute, just use booleans as true or false.
<option t:attr="selected=true">
My Company
</option>
The previous template will be rendered as:
<option selected>
My Company
</option>
Note
Since XML does not have the concept of “boolean attributes”,
this feature may break your output if you are using XML.
To to remove and already defined attribute, use false as attribute value
<div class="foo" t:attr="class=false">
My Company
</div>
The previous template will be rendered as:
attr-append
Twital allows you to create HTML/XML attributes in a very simple way.
t:attr-append is a different version of t:attr:
it allows to append content to existing attributes instead of replacing it.
<div class="row" t:attr-append=" condition ? class=' even'">
class will be "row even" if 'i' is odd.
</div>
In the same way of t:attr, condition and the value of attribute can be any valid Twig expression.
<div class="row"
t:attr-append=" i mod 2 ? class=' even'|upper">
class will be "row EVEN" if 'i' is odd.
</div>
When not needed, you can omit the condition instruction.
<div class="row" t:attr-append=" class=' even'">
Class will be "row even"
</div>
content
This attribute allows to replace the content of a note with the content of a variable.
Suppose to have a variable foo with a value My name is John and the following template:
<div id="pagination" t:content="foo">
This <b>content</b> will be removed
</div>
The output will be:
<div id="pagination">My name is John</div>
This can be useful to put come “test” content in your templates that will have a nice aspect on WYSIWYG
editors, but at runtime will be replaced by real data coming from variables.
replace
This attribute acts in a similar way to content attribute,
instead of replacing the content of a node, will replace the node itself.
Suppose to have a variable foo with a value My name is John and the following template:
<div id="pagination" t:replace="foo">
This <b>content</b> will be removed
</div>
The output will be:
This can be useful to put come “test” content in your templates that will have a nice aspect on WYSIWYG
editors, but at runtime will be replaced by real data coming from variables.