Twig Templating Engine

The templating engine used by BranchCMS is Twig, a popular templating engine/language used in a lot of PHP projects. It is developer friendly and allows your website's templates to include content and have logic. 

All of the core Twig syntax, functions, tags and tests are supported, and we have extended it to have additional functionality for BranchCMS.

Twig overview

Each template for your website will be a mix of HTML and Twig syntax. The Twig code could be variables or expressions, which get replaced with values when the template is rendered, and tags, which control the logic of the template.

Below is a basic example showing a Blog content template for displaying a list of posts.

{% for post in posts %}
    <h2><a href="{{ post.url }}">{{ post.postTitle }}</a></h2>
    {% if post.abstract %}
        {{ post.abstract|replace({'<p>': '<div>', '</p>': '</div>' }) }}
    {% else %}
        {{ post.content|truncate_html(500) }}
    {% endif %}
    <div><a href="{{ post.url }}">Read more</a></div>
{% endfor %}

There are two kinds of tags in Twig:

  • Logic tags: {% ... %}
  • Output tags: {{ .... }}

Logic tags

Logic tags control what happens in your templates. It's used in the following instances:

  • setting values
  • test conditionals
  • loop through arrays
  • execute other statements

The syntax for logic tags always begins with {% and ends with %}. Below are some examples:

<p>Is it time to go home?</p>

{% set hour = _core.date('G') %}
{% if hour >= 16 %}
    <p>Yes! Go home!</p>
{% else %}
   <p>No! Say here.</p>
{% endif %}

Note: you never place tags within other tags in Twig. 

These are wrong:

{% set title = {{ item.itemName }} %}
{% set hasAbstract = {% if item.abstract %} 'Yes' {% else %} 'No' {% endif %} %}

These are correct:

{% set title = item.itemName %}
{% set hasAbstract = item.abstract ? 'Yes' : 'No' %}

Output tags

Output tags displays the result of an expression in your templates. It's primarily used to display a variable value or the result of a function.

 The syntax for logic tags always begins with {{ and ends with }}.  You can put just about anything between those tags so long as it can be evaluated to a string. Below are some examples:

<h2>{{ item.itemName }}</h2>
<p>Name: {{ item.firstName|capitalize }}<p>
{{ post.abstract|replace({'<p>': '<div>', '</p>': '</div>' }) }}

There are some instances, however, when no output is returned. An example of that is when using the append, prepend or set functions for HTML objects. For example, the following code will set a "data" attribute on an image tag, but it will not output anything.

{{ image.set('data-custom', 'data-value') }}

Variables

The primary use of templates is to output some content and that content is stored in variables. You use the output tags to display a variable.

{{ variableName }}

If the variable is an array or HTML object you can access values in the array or object using the dot (.) syntax.

{{ item.itemName }}

If for some reason the array/object key contains special characters (like "-" that would be interpreted as the minus operator) then use the attribute function instead to access the value.

{{ attribute(item, 'data-foo') }}

If the variable that you're trying to access doesn't exist then nothing is displayed. That even applies if you are using a filter on a non-existent variable.

Using a variable as an object key

If you're trying to use a variable as an object key then you need to wrap the variable in parenthesis.

Wrong

{% set data = data|merge({variableName: 'value'}) %}

Correct

{% set data = data|merge({(variableName): 'value'}) %}