Skip to content

Latest commit

 

History

History
149 lines (94 loc) · 4.77 KB

twig-primer.md

File metadata and controls

149 lines (94 loc) · 4.77 KB
Raw

Twig Primer

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

This is only meant as a primer, not a comprehensive documentation of everything Twig can do.

To learn more, visit the Continued Reading section at the bottom of this page or refer directly to the official Twig documentation .

Three Types of Twig Tags

There are three types of tags in Twig:

  • Logic Tags
  • Output Tags
  • Comment Tags

Let's review each one in more detail.

Logic Tags

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

Logic tags don't output anything to the template on their own.

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

<p>Is it quitting time?</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 Twig can evaluate it into a string.

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

Output tags are only for outputting to the template, so you never place output tags within statement tags in Twig.

These examples are incorrect:

{% 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:

Comment Tags

You can leave comments for future self in the code using comment tags. Twig won't evaluate anything inside the comment tags; it will simply pretend they don’t exist.

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

{# Loop through the recipes #}

Anything put inside of the comments tags will not render to the final template, not even as an HTML comment.

Variables

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

You can assign your own variables using the set tag:

{% set style = 'stirred' %}

{{ style }}

Additionally, 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
  • Templates that are loaded as the result of a matching entry URL get an entry variable (see {entry:docs/routing:link} 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 you can use 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.
  • Twig Templates in Craft is a video course by Mijingo that aims to get you comfortable with using Twig in Craft.
  • 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.