Twig Syntax and Features

In this section of the Zid Themes Documentation, we delve into the heart of theme customization: the Twig template engine. Twig offers a powerful and flexible syntax for embedding logic and data into your theme's design. This guide will walk you through the essential syntax, tags, functions, and filters you'll need to create dynamic themes.

Understanding the Basics of Twig

Twig simplifies the infusion of data into templates using two primary syntax forms:

{{ ... }}: This notation is used to display the content of variables.
{% ... %}: This structure is employed to execute logic-based operations such as conditions and loops.

Essential Twig Tags

Zid supports a subset of Twig's tags to maintain simplicity and performance. Below are the tags available for use in your themes:

extends
block
include
for
if, elseif, else
set

Extending Templates with `extends` and `block`

Twig's template inheritance feature is instrumental in building a base layout, which can then be extended by child templates for customization. Here's an illustrative example of how to use the extends and block tags within a Zid theme:

{% extends "layout.twig" %}

{% block title %}Custom Page Title{% endblock %}
{% block head %}
    <!-- Additional elements for the <head> can be placed here -->
{% endblock %}
{% block content %}
    <!-- This is where your main page content will reside -->
{% endblock %}
{% block footer %}
    <!-- Customize the footer by overriding this block -->
{% endblock %}

{{ zidapi_script|raw }}
<script type="text/javascript" src="{{ asset_url ~ 'main.js' }}"></script>

In this example, the content block in home.twig will replace the corresponding content block within layout.twig. This pattern of inheritance ensures that you can maintain consistent design elements across different pages while customizing content as needed.

Remember that you can also include additional scripts or API calls like zidapi_script within your templates to enhance functionality or track analytics.

Now here is an example of a base layout file in Twig, layout.twig, and how it is structured:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}{% endblock %} | Your Site Name</title>
    <link rel="stylesheet" href="path_to_bootstrap">
    {% block head %}{% endblock %}
</head>
<body>
    <div class="container">
        {% block header %}{% endblock %}
        {% block content %}{% endblock %}
        {% block footer %}{% endblock %}
    </div>
    <script src="path_to_main_js"></script>
    <script src="path_to_bootstrap_js"></script>
</body>
</html>

This base layout can then be extended by child templates, which can override specific blocks such as title, content, and footer.

Including Sub-templates with `include`

The include tag allows you to incorporate other templates into the current one, similar to a 'copy-paste' action:

{% block sidebar %}
    {{ include('sidebar.twig') }}
{% endblock %}

Conditional Logic with `if`, `elseif`, `else` and `endif`

Twig's if statement allows you to conditionally display content. It can be combined with elseif and else for more complex conditions:

{% if user.is_active %}
    Welcome, {{ user.name }}!
{% elseif user.is_guest %}
    Welcome, guest! Please register.
{% else %}
    Access denied.
{% endif %}

Variable Assignment with `set`

Define or modify variables within your templates using the set tag:

{% set greeting = 'Hello, World!' %}
{{ greeting }}

Twig Filters

Filters in Twig modify the content of variables before they are used. Zid supports the following filters:

escape: Ensures the output is safe to render by escaping HTML characters.
length: Returns the number of items in a sequence or characters in a string.
raw: Outputs raw, unescaped data.

Twig Functions

Functions perform complex operations on variables. Zid provides these functions for your templates:

range: Generates a sequence of numbers.
include: Incorporates other templates.

For a comprehensive understanding and in-depth technical details of Twig, explore official Twig 3.x documentation.

Last modified: 4 months ago

Twig Syntax and Features

Understanding the Basics of Twig

Essential Twig Tags

Extending Templates with extends and block

Including Sub-templates with include