Creating templates

We talked about the general architecture in the last part. Now we are focusing on what is or should be inside the templates themselves and how to use the various features Twig ships with.

1. How to make extends, embeds and uses work?
2. What’s so special with components and how to use them?
3. How to use the various template features like insert tag rendering, images or translations?
4. How should I name my templates?

Reusing template parts

Twig supports a lot of different ways how to reuse Template parts and Contao enhances nearly all of them as well with the managed namespace) concept: Extends, includes, embeds, horizontal reuse and macros.

Extends

A template can extend another one, called the parent or more general the base template. When extending a template, your template cannot contain content outside blocks, anymore, but you can adjust blocks of the parent template.

• Typically, you want to replace and extend at the same time. This means, you name your template like the parent to make the loader choose yours when rendering, and then you reuse as much as possible from the parent by extending it.

• This isn’t mandatory, though — variant templates are a good example for when you would want to create a new template but still only adjust things from the original one.

• You can also use base templates like abstract base classes if you want to share a basic markup (implementation) across multiple children. The content_element/_base.html.twig is an example for this. Although this template does not contain a lot of markup, having it adds another handy use-case: If you want to adjust all content elements, e.g. by adding something to the wrapper, you now only need to adjust a single file.

Read more about the original implementation of the extends tag in the official Twig documentation.

{# Outputs a product with title and some details. #}
<section class="product">
    {% block title %}<h1>{{ product.title }}</h1>{% endblock %}
    
    {% block details %}
        <ul class="product--details">
            {% for detail in product.details %}
                <li>{{ detail }}</li>
            {% endfor %}
        </ul>            
    {% endblock %}
</section>

{% extends "@Contao/product.html.twig" %}

{% block title %}
    {{ parent() }}
    <img scr="{{ product.imageSrc }}" alt="{{ product.title }}" />
{% endblock %}

<section class="product">
    <h1>Fair-trade Coffee</h1>
    <img src="assets/images/coffee_package.jpg" title="Fair-trade Coffee"/>
    <ul class="product--details">
        <li>Nice aroma</li>
        <li>Lots of caffeine</li>
    </ul>            
</section>

With the {{ parent() }} function you can insert the content of the current block as it was defined in the parent template.

Includes

If you want to include a whole template in another one, you can either use the {% include %} tag or the include() function. While the tag looks analogous to when embedding templates, the function returns the template as a string, which might come handy in rare cases, where you need to further process the result before outputting. Which one you choose is a matter of taste.

Read more about the original implementation of the include tag or the include function in the official Twig documentation.

{% block button_container %}
    <div class="call-to-action">    
        <button>
            {% block button_inside %}
                {{ title|default('Click me!') }}
            {% endblock %}
        </button>
    </div>
{% endblock %}

<div class="advertisement">
    <quote>
        Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
        eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
        voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
    </quote>
    
    {% include "@Contao/_action_button.html.twig" with {title: 'Buy this poetry on a shirt!'} %}
</div>

Embeds

Sometimes you want to include a template, but at the same time adjust some of its blocks. For this, you can embed the template.

Read more about the original implementation of the embed tag in the official Twig documentation.

<div class="advertisement">
    <quote>
        Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
        eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
        voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
    </quote>
    
    {% embed "@Contao/_action_button.html.twig" with {title: 'Buy this poetry on a shirt!'} %}
        {% block button_inside %}
            <img src="files/poetry.svg" alt="Poetry"> {{ parent() }}
        {% endblock %}
    {% endembed %}
</div>

Horizontal reuse

Similar to what traits are for classes in PHP, in Twig the {% use %} tag allows to reuse blocks of other templates without extending them. Used blocks are not output by default, but instead made available to the block() function.

Horizontal reuse is one of the most powerful parts of Twig. At the same time it’s the most complex one. So let’s dissect the various parts needed for it to work.

• The block() function renders a block, that is available to the current template. Available means: defined in the same file, any parent template or manually imported by a {% use %} statement (see below).

  {% block foo %}Foo {{ bar }}{% endblock %}
  
  {# Output the "foo" block again #}
  {{ block('foo') }}

• When using block(), the function renders the given block with the current template parameters. To render it in a different context, you can surround it with the {% with %} … {% endwith %} block tag, which allows defining template parameters, that are scoped to just this block. By default, the defined parameters are merged with the current ones, to suppress merging, you can add the only keyword.

  {# Output the "foo" block with the "bar" parameter being set to "baz" #}
  {% with {bar: 'baz'} only %}
    {{ block('foo') }}
  {% endwith %}

• Finally, the {% use %} statement imports all blocks of the given template without outputting them. They will
  then be available to be output using a combination of {% with %} and the block() function. When importing, it could potentially happen, that there are blocks with identical names. To work around this, you can rename the blocks while importing.

  {% use "@Contao/_foo.html.twig" %}
  {% use "@Contao/_cat.html.twig" with sound as meow  %}
  {% use "@Contao/_dog.html.twig" with sound as bark %}
  
  {# Output the "sound" block of the cat template, that was imported as "meow" #}
  {{ block('meow') }}

Read more about the original implementation of the use tag, the with tag and the block function the in the official Twig documentation.

{% use "@Contao/_action_button.html.twig" %}

<div class="advertisement">
    {% block description %}{% block %}
    {{ block('button_container') }}
</div>

{% extends "@Contao/_advertisement.html.twig" %}

{% block description %}
    <quote>
        Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
        eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
        voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
    </quote>
{% endblock %}

{% block button_inside %}
    <img src="files/poetry.svg" alt="Poetry"> {{ parent() }}
{% endblock %}

Macros

Twig also features macros via the {% macro %} tag. These are very similar to how PHP functions work and also allow to reuse template logic. Head over to the Twig docs, to read more about how the macro tag works in detail.

{% macro tree(node) %}
    <ul>
        {% for child_node in node.children %}
            <li>
                {% if child_node.children|length %}
                    {{ _self.tree(child_node) }}
                {% else %}
                    {{ child_node.value }}
                {% endif %}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

<div class="tree">
    {{ _self.tree_node(tree) }}
</div> 

Contao components

By understanding how components work in Contao, you can get the most out of the core templates. You also might want to reuse them in your own code. Please familiarize yourself with the concept of horizontal reuse as we are heavily going to make use of it.

Let’s look at a real world example first. In Contao, a template component could look like this (taken from @Contao/component/_figure.html.twig, a bit simplified):

{% use "@Contao/component/_picture.html.twig" %}

{% block figure_component %}
    {% set figure_attributes = attrs()
        .mergeWith(figure.options.attr|default)
        .mergeWith(figure_attributes|default)
    %}
    <figure{{ figure_attributes }}>
        {% if not figure.linkHref|default %}
            {# Media #}
            {% block media %}
                {{ block('picture_component') }}
            {% endblock %}
        {% else %}
            {# Media wrapped with link #}
            {% block media_link %}
                {% set link_attributes = attrs(figure.linkAttributes(true)|default)
                    .set('title', figure.metadata.title)
                    .mergeWith(figure.options.link_attr|default)
                    .mergeWith(link_attributes|default)
                %}
                <a{{ link_attributes }}>{{ block('media') }}</a>
            {% endblock %}
        {% endif %}

        {# Caption #}
        {% block caption %}
            {% if figure.metadata and figure.metadata.caption %}
                {% set caption_attributes = attrs()
                    .mergeWith(figure.options.caption_attr|default)
                    .mergeWith(caption_attributes|default)
                %}
                <figcaption{{ caption_attributes }}>
                    {%- block caption_inner -%}
                        {{- figure.metadata.caption|raw -}}
                    {%- endblock -%}
                </figcaption>
            {% endif %}
        {% endblock %}
    </figure>
{% endblock %}

Wow, there is a lot going on. For a moment, let’s remove the HTML attributes and strip the example further down.

It is no easier to see the <figure> HTML tag with a <figcaption> and some media, optionally wrapped in an a tag. Everything is placed in a block called figure_component.

{% block figure_component %}
    <figure>
        {# Media, optionally wrapped in a link #}
        {% if not figure.linkHref|default %}
            {% block media %}
                … here would be some media, like a picture …
            {% endblock %}
        {% else %}
            <a>{{ block('media') }}</a>
        {% endif %}

        {# Caption #}
        <figcaption>
            … here goes the caption …
        </figcaption>
    </figure>
{% endblock %}

Now, try going back to the original version. You’ll find, that the “media” bit isn’t implemented in the template, but instead uses and renders another component, the picture component (yes we’ve got template reuse everywhere). You also see the “set and merge” pattern being heavily in use (more on that further down). And we’ve got a lot of blocks. All this makes the template look more complex, but extremely adjustable on the other hand.

Adjusting components

Talking about adjusting: You saw in the examples earlier in this article how you would adjust blocks introduced by components. But how would you adjust a component itself (globally)?

{% use "@Contao/component/_picture.html.twig" %}

{% block image %}
    {% set img_attributes = attrs().addClass('my-image').mergeWith(img_attributes|default) %}
    <div>{{ parent() }}</div>
{% endblock %}

Grouped parameters

Until now, we only looked at the figure and picture components. They are special in a way, that every data they output, comes from a single Figure object (note the figure template parameter being used everywhere). Most of the time, you want to use several parameters, though.

If you dare, take a look at the list component, another very powerful, yet complex component: source code. Don’t worry about the javascript magic to sort and randomize lists at the moment but instead focus at the very beginning. Here is a stripped down version:

{% block list_component %}
    {% set list = list|default(_context) %}
    …
    
    <{{ tag_name }}>
        …
    </{{ tag_name }}>
{% endblock %}

The component begins with a variable declaration for a variable called list (not by accident: like the component), that, if not already existing, will be set to the current context using the special _context variable. Inside the component, everytime a parameter is used, the list version is used: list.items, list.randomize_order, and so on.

This effectively allows passing parameters individually or grouped under a Twig object. But why? When outputting multiple components, you can neatly group the data (already in the controller). By using the default names (here rendering with parameters: ['headline' => […], 'list' => […]]), you can omit any mapping needed with a {% with %} block. More importantly, the component’s parameters will never collide if named the same.

{# Output a headline and a list #} 
{{ block('headline_component') }}
{{ block('list_component') }}

On the other hand, manually outputting blocks is less cumbersome without the additional group:

{% with {tag_name: 'h2', headline: 'My headline' } %}
    {{ block('headline_component') }}
{% endwith %}

Template features

The Contao Twig extension does most of the setup needed to provide our custom functionality, like the managed namespace, the input encoding tolerant escapers, the legacy interoperability, or several filters and functions to make your life easier. On top of that, many Twig features just work out of the box for us.

• Replacing and handling insert tags
• Handling HTML attributes
• Adding shared page content such as scripts, styles or schema information
• Generating images on the fly
• Formatting and enhancing text
• Handling translations
• Generating and manipulating URLs
• Rendering content elements and front end modules

Insert tags

If you want to output a string, that contains insert tags, you, as the template designer, need to decide if and how it should get treated. In case insert tags should get replaced, you can precisely control what to encode and what to keep raw (see table below): Everything, all but the result of evaluating the insert tags, or nothing at all. This way you can keep the security risk low while still allowing features.

The examples in the following table use the context ['text' => 'This is some <b>very</b> {{br}} rich text.] that both includes some user input HTML and the {{br}} insert tag (which evaluates to <br> if being replaced). The given output examples were generated using the escaping strategy for HTML.

Think about your scenario, before deciding which option to use. Should insert tags even be replaced? If so, they might for instance output HTML. Do you trust this? And, sticking to the HTML example, should a user be able to write HTML? With |insert_tag_raw you can for example allow an editor to use the {{br}} insert tag while still disallowing the use of any custom HTML around it.

Response context

Sometimes a template only includes part of a page, like a content element, but still wants to contribute content that is global to the page.

For this, you can use the add tag in Contao. It allows adding content to the end of the document head or body. If you want the block to be output only once (no matter how often the template is rendered on the current page), you can provide a name. This is especially helpful when adding a generic javascript code or styles, that do not make sense getting inserted multiple times.

{# Add code to the end of the document body #}
{% add to body %} … {% endadd %}

{# Add code to the end of the document head #}
{% add to head %} … {% endadd %}

{# Add code to the end of the document body once #}
{% add "foo" to body %} … {% endadd %}

{# Add code to the end of the document head once #}
{% add "bar" to head %} … {% endadd %}

If you want to add JSON-LD metadata to the current page, you can use the add_schema_org function. It expects an array of data and returns nothing. For this, you will typically want to wrap a call to it in Twig’s do tag:

{% do add_schema_org(…) %}

HTML Attributes

HTML attributes are a heavily used feature in HTML. In the context of templates, they are also one of the primary things, that people want to adjust. This is why we created the HtmlAttributes class together with the attrs() function to create an instance of said class.

The HtmlAttributes class features a lot of helper methods in a fluent API style. With it, you can easily parse, merge and compose attributes on the fly. Anything you pass to the attrs() function will be passed to the classes' constructor: This could either be an associative array of attributes, a string of attributes that will get parsed or another HTMLAttributes object that will get merged.

<div id="main" class="{{ classes|join(' ') }}"{% if tooltip|default %} data-tooltip="{{ tooltip }}{% endif %}">
    {{ text }}
</div>

<div{{ attrs().set('id', 'main').addClass(classes).setIfExists('data-tooltip', tooltip|default) }}>
    {{ text }}
</div>

We are heavily using a pattern, that we call “set and merge”, in the core’s templates. Here, instead of outputting the attributes directly, a variable is assigned first and the same variable (falling back to an empty string) is used when constructing the attributes, effectively merging any previously set data. With this change, extenders of the template, that only want to adjust attributes, do not have to overwrite anything. As their code gets executed first, they can simply create the variable with the same pattern, and it will then get merged by the parent.

{% set text_attributes = attrs()
    .set('id', 'main')
    .addClass(classes)
    .setIfExists('data-tooltip', tooltip|default)
    .mergeWith(text_attributes|default)
%}
<div{{ text_attributes }}>
    {{ text }}
</div>

{% extends "@Contao/text_example.html.twig" %}

{% set text_attributes = attrs().addClass('custom-class').mergeWith(text_attributes|default) %}

Images

The figure and picture components are suited to render any built Figure object. In case you cannot or don’t want to create a Figure in the controller, you can alternatively use the figure function to build a Figure instance on the fly. Internally, this uses the FigureBuilder from the Contao image studio. In case you also want to create a picture/resize configuration on the fly, you can use the respective picture_configuration function.

{# It's enough to specifiy the resource and size… #}
{% set figure = figure('path/to/my/image.png', '_my_size') %}

{# …but you can also go wild with the options: #}
{% set figure = figure(id, [200, 200, 'proportional'], { 
  metadata: { alt: 'Contao Logo', caption: 'Look at this CMS!' },
  enableLightbox: true,
  lightboxGroupIdentifier: 'logos',
  lightboxSize: '_big_size',
  linkHref: 'https://contao.org',
  options: { attr: { class: 'logo-container' } }
}) %}

{# You can even use a custom - on the fly - picture configuration: #} 
{% set special_size = picture_config({
    width: 400,
    height: 400,
    resizeMode: 'proportional',
    sizes: '0.75,1,1.5,2',
    items: [{
        width: 200,
        height: 100,
        media: '(max-width: 140px)',
    }]
}) %}
{% set figure = figure(uuid, special_size) %}

You can then query the object for things like metadata or sizes and/or output it as an image, for example using the pre-made _figure component:

{% use "@Contao/component/_figure.html.twig" %}

{# Create the figure inline or use the one already in our context #}
{% set my_figure = figure(…) %}

{# Output it using the figure component #}
{% with {figure: my_figure} %}{{ block('figure_component') }}{% endwith %}

Formatting

You can use the highlight and highlight_auto filters to generate code highlighting with the scrivo/highlight.php library. You can either pass a language to use or let the library guess the language (highlight_auto). In the latter case, you can optionally constrain the selection to a given subset of languages.

{# Output code directly as a string… #}
<pre><code>{{ code|highlight(language) }}</code></pre>

{# … and/or query the result properties: #}
{% set highlighted = code|highlight_auto %}
The detected language was {{ highlighted.language }} with a relevance of {{ highlighted.relevance }}.

The format_bytes filter transforms a number representing a file size in bytes into a human-readable form. It therefore uses the MSC.decimalSeparator, MSC.thousandsSeparator and UNITS declarations from the global translation catalogue.

{# outputs 1536 #} 
{{ size }}

{# outputs "1.5 KiB" #}
{{ size|format_bytes }}

{# outputs "1.500 KiB" #}
{{ size|format_bytes(3) }}

Translations

The Symfony Twig bridge includes a trans tag and function to handle and output translations. If you want to define the default translation domain, that is used in the whole template, you can use the trans_default_domain tag. Read more about this in the Symfony Twig documentation.

{% trans_default_domain "contao_default" %}

<div>
    {# Output a translation using the default domain: #}
    <a href="more.html">{{ 'MSC.readMore'|trans }}</a>

    {# Output a translation containing placeholders and a custom domain. You
       can either use an array with unnamed parameters, or an object, that
       explicitly defines replacements: #}
    {{ 'tl_race.result'|trans([best_time], 'contao_race') }}
    {{ 'tl_race.result'|trans({'%best%': best_time}, 'contao_race') }}
</div>

URLs

To generate URLs from within Twig templates, you can use the path() function, that is shipped with the Symfony Twig bridge. Read more about this function in the Symfony Twig documentation.

<a href="{{ path('my_custom_route', {id: 42}) }}">Watch for this!</a>

The prefix_url filter prefixes relative URLs with the request base path. This is needed when dealing with relative URLs on a page that does not set a <base> tag.

{# will outpuot something like "https://example.com/some/relative/url.html" #}
{{ 'some/relative/url.html'|prefix_url }}

Render Content Elements

You can render content elements directly in your Twig templates via the content_element() function. This function either takes a database ID of an existing content element, a ContentElementReference object - or just the type of a content element. In the latter case you can then also define all the options with which this content element should be rendered. This allows you to render content elements on the fly without having to define them in the database.

{# Render a specific content element from the database #}
{# This is similar to the `insert_content` insert tag #}
{{ content_element(15) }}

{# Render a `gallery` content element on the fly #}
{{
    content_element('gallery', {
        multiSRC: data.myGallery,
        sortBy: 'random',
        perRow: 4,
        limit: 12,
        fullsize: true
    })
}}

Render Front End Modules

You can render front end modules directly in your Twig templates via the frontend_module() function. This function either takes a database ID of an existing front end module - or just the type of a front end module. In the latter case you can then also define all the options with which this front end module should be rendered. This allows you to render front end modules on the fly without having to define them in the database.

{# Render a specific front end module from the database #}
{# This is similar to the `insert_module` insert tag #}
{{ frontend_module(42) }}

{# Render a `navigation` front end module on the fly #}
{{
    frontend_module('navigation', {
        levelOffset: 1,
        navigationTpl: 'nav_custom',
    })
}}

Naming convention

Because of the shared @Contao namespace, it is important, that the Contao ecosystem tries to stick to a common naming convention. For the sake of readability, we are omitting the @Contao/ prefix to the logical name in the following examples.

Directory structure

Twig allows the usage of directories as part of the template name. For extensions or if you want to use the application’s main template directory, you might want to read the part about how to properly set up the Twig root first.

Variants

In Contao, you can create templates in multiple variants and let back end users pick the one they need. Read more about the architecture and how they are used in the template variants section.

since 5.2 If you want to change the display names of the templates, that are selectable in the back end dropdowns for content elements or frontend modules, you can create translations for them in the templates translation domain. The translation ID is equal to the template identifier:

# translations/templates.en.yaml
content_element/text: 'Default text'
content_element/text/special: 'Special text'

Partials and components

Partials are files that will never be rendered directly but included/embedded/used or extended from only. There is no difference in how they work, but the convention to distinguish them allows to easier find the main controller templates.