Twig Quick Start and Twig Tem­plat­ing Key Concepts

Twig is the templating language used to display your content in your Craft CMS templates. While there is a lot to learn about Twig, this article will focus on a few key concepts that can get you started, and take you far.

Let's over-simplify and say that nearly all that we are doing in Twig falls into the following 5 groups:

  1. Output content
  2. Loop through repeating content
  3. Display conditional content
  4. Modify content in our templates
  5. Optimize our code

Output content

To display content in out templates, we use the Twig output tag:

{# Output a Craft Global #}
{{ siteName }}

{# Output a slug from your url #}
{{ craft.request.getSegment(2) }}

{# Output a translatable string #}
{{ "This is just text" }}
{{ "This is translatable text"|t }}

{# Output a translatable variable #}
{{ siteName|t }}

Loop through repeating content

Some content in our templates can't be output directly to the template because it contains an multiple peices of content. To loop through content, we use Twig's action tag:

{# Loop through several articles #}
{% for entry in craft.entries.section('articles') %}
    {{ entry.title }}

    {# Loop through a table field within our content #}
    {% for row in entry.tableFieldName %}
        {{ row.columnName }}
    {% endfor %}

    {# Loop through an Assets field within our content #}
    {% for image in entry.assetFieldName %}
        {{ image.filename }}
    {% endfor %}

    {# Loop through an Entry Relations field within our content #}
    {% for relatedEntry in entry.entriesFieldName %}
        {{ relatedEntry.title }}
    {% endfor %}

{% endfor %}

Display conditional content

When we need to conditionally display content, we can use logic in our templates.

{# The if statement checks to see if something is true before displaying it  #}
{% if currentUser.admin %}
    {# Display an edit link for our admin #}
    {{ entry.getCpEditUrl() }}

{% endif %}

{# The if/else statement can check multiple conditions #}
{% if entry.type == 'link' %}
    {# Display fields related to your 'link' entry type #}

{% elseif entry.type == 'video' %}	
    {# Display fields related to your 'video' entry type #}

{% else %}
    {# Display our default post type #}

{% endif %}

{# The switch tag can compare multiple conditions as well  #}
{% switch entry.type %}

    {% case "link" %}

        {# Display fields related to your 'link' entry type #}

    {% case "video" %}

        {# Display fields related to your 'video' entry type #}

    {% default %}

        {# Display our default post type #}

{% endswitch %}

Modify content in our templates

Sometimes we need to modify the content we output in our templates. We can do so using Twig functions and filters:

{# Use the raw filter to output HTML content as HTML #}
{{ entry.textareaFieldFullOfHtml|raw }}

{# Use the translate filter to translate content in the translations folder #}
{{ "This is translatable text"|t }}

{# Use multiple filters by chaining them together 
   In this example, we strip the HTML tags from our description, santize the output so any special characters are escaped, and make sure that we are only displaying the first 160 characters #}
{{ entry.description|striptags|escape|slice(0,160) }}

Optimize our code

All of the above Twig concepts help us display content in our templates. Twig also gives us some handy tools that make it easier to manage the code in our templates:

{# Create a variable to use later. #}
{% set bodyId = 'homepage' %}

{# Include code from a separate template file #}
{% include 'folder/filename' %}

A variable you created can be used in an included file.

{# Your homepage template #}
{% set bodyId = 'homepage' %}
{% include '_partials/header' %}
{# Your '_partials/header' template could then include  #}
<body id="{{ bodyId }}">

You can also override variables in a layout template

{# Your '_layouts/layout' template might look like the following #}
<body id="{{ bodyId }}">

    {% block content %}{% endblock %}

{# Then you can create a template where you extend your layout with more specific content #}
{% extends '_layouts/layout' %}

{% set bodyId = 'homepage' %}

{% block content %}

    {# The HTML and body content for your homepage #}

{% endblock %}

Twig is a powerful and flexible templating language. While we have over-simplified things here, most of your daily Twig templating needs will fall within these 5 categories. Understanding these concepts will help you get started, troubleshoot common template errors, and build a strong foundation for managing website templates using Twig.

Level up in Craft CMS with practical examples, snippets, and patterns.
Craft The Planet emails are sent out several times a week.