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.

Images

You can output a figure directly from within your template by using the contao_figure Twig function. The function expects a resource (uuid, id, path) as the first and the image size as the second argument. If you want to specify more config, you can pass a config object as the third argument.

In the config object you can configure the same things you would as when using the FigureBuilder (see [reference][FigureBuilderOptionsReference]). In fact, under the hood, the Twig function uses [PropertyAccess][PropertyAccess] to configure a FigureBuilder instance. This is why you can also use the same short notation you expect from Twig when accessing variables (e.g. size instead of setSize). In the case of metadata, you can also just pass an object which will internally be converted into Metadata.

{# It's enough to specifiy the resource and size… #}
{{ contao_figure('path/to/my/image.png', '_my_size') }}
    
{# …but you can also go wild with the options. #}
{{ contao_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' } }
}) }}

If you want to use a complex size configuration for just one image, you do not need to create a global configuration. Instead, use the picture_config Twig function, pass it the configuration and use the result as the size argument of the contao_figure function:

{% 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)',
    }]
}) %}

{{ contao_figure(uuid, special_size) }}

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>

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.