Twig Primer

Here’s a rundown of the core concepts in Twig, the templating engine used by Craft.

Logic Tags #

Logic tags control what happens in your template. They can set variables, test conditionals, loop through arrays, and much more.

Their syntax always begins with “{%” and ends with “%}”. What happens in between is up to the tag you’re using.

<p>Is it happy hour?</p>

{% set hour = now|date("G") %}
{% if hour >= 16 and hour < 18 %}
    <p>Yes!</p>
{% else %}
    <p>Nope.</p>
{% endif %}

Output Tags #

Output tags are responsible for printing things out to the rendered HTML.

Their syntax always begins with “{{” and ends with “}}”. You can put just about anything inside them – as long as it can be evaluated into a string.

<p>The current time is {{ now|date("g:i a") }}.</p>

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

These are wrong:

{% set entry = craft.entries.section( {{ sectionId }} ).first() %}
{% set entry = craft.entries.section( {% if filterBySection %} sectionId {% endif %} ) %}

These are correct:

{% set entry = craft.entries.section( sectionId ).first() %}
{% set entry = craft.entries.section( filterBySection ? sectionId : null ) %}

Resources:

Comments #

You can leave comments for future self in the code using comment tags. Comments won’t ever be evaluated or printed out; Twig will simply pretend they don’t exist.

Their syntax always begins with “{#” and ends with “#}”.

{# Holy cow Twig is awesome! #}

Variables #

Variables in Twig are just like variables in Javascript or any other programming langauge. There are different types of variables – strings, arrays, booleans, and objects. You can pass them into functions, manipulate them, and output them.

All of your Craft templates are pre-loaded with a few global variables; templates that are loaded as a result of a matching route get pre-loaded with the variables defined by the route’s tokens; and templates that are loaded as the result of a matching entry URL get an “entry” variable (see Routing for more details).

Filters #

You can manipulate variables with filters. The syntax is the variable name followed by a pipe (|) followed by the filter name:

{{ siteName|upper }}

Some filters accept parameters::

{{ now|date("M d, Y") }}

Resources:

Functions #

Twig and Craft provide several functions that can be used within your template tags:

<h3>Watch me count to ten!</h3>
<ul>
    {% for num in range(1, 10) %}
        <li class="{{ cycle(['odd', 'even'], loop.index0) }}">
            {{ num }}
        </li>
    {% endfor %}
</ul>

Resources:

Continued Reading #

There are several learning resources available online for learning Twig:

  • Twig for Template Designers documents all of Twig’s features in detail. It can be overly technical at times, but we still recommend you read through it.
  • Straight up Craft has some great articles on how to use Twig within Craft.
  • Twig for Designers is an in-progress eBook that aims to explain how Twig works to non-developers.