Articles

The Twig templating engine provides a debugging tool.

Drupal 8’s implementation also adds an extra tool that lets you locate the template that outputs markup.

Warning: Enabling Twig debugging may break some parts of the site, especially Views. See this issue.

Enable Debugging

You enable Twig debugging in sites/default/services.yml.

Set the debug variable to true and clear the cache:

How Twig Normally Works

By default, the Twig theming engine compiles templates into PHP code and stores the compiled code in memory. This compiled code is not ideal for development because changes to Twig templates do not immediately reflect on your Drupal site.

Once Twig finishes rendering markup, the Render API adds another layer of caching. It stores the markup created by Twig in such a way that Twig is not involved in subsequent page requests, effectively ignoring Twig debugging settings.

To find out which template is generating the markup for a specific element, you can use Twig’s built-in debug option. This setting will display HTML comments alongside the rendered output, which includes the theme hooks used, suggested template file names, and identifies the exact Twig file used to render a specific part of your markup.

Filters in Twig can be used to modify variables. Filters are separated from the variable by a pipe symbol. They may have optional arguments in parentheses. Multiple filters can be chained together. The output of one filter is passed to the next.

Example:

{{ content|safe_join(", ")|lower }}

You may need to render an element before filtering it:

Twig provides a number of convenient functions that can be used directly in templates.

List of Twig Functions

Drupal core adds several custom functions specific to Drupal. They are defined in the TwigExtension class.

From the official Twig documentation: “Macros are comparable to functions in regular programming languages. They are useful to put often-used HTML idioms into reusable elements to not repeat yourself.”

{% macro input(name, value, type, size) %}
  
{% endmacro %}

Macros differ from native PHP functions in several ways:

To make Drupal 8 theming as performant as possible and provide more flexibility in Twig templates, follow these best practices:

The general idea in Drupal 8 is that you want to avoid generating HTML directly in the PHP code of your custom module. Instead, you want this to go into Twig templates. To create new Twig templates in your module, follow these steps.

Step #1: Define hook_theme in your .module file
Create a [module].module file if it doesn’t already exist, and add the code that defines each of your Twig templates. The key of each item in the array is what you will need to call the template later. Do not use dashes in the file name.

Twig templates can be extended using the following syntax:

{% extends 'html.twig' %}

For more details, see https://symfony.com/doc/current/templates.html#template-inheritance-and-layouts

Sub-themes, like any other theme, differ in one key way: they inherit resources from their parent theme. There are no limitations to the chaining capabilities connecting sub-themes to their parents. A sub-theme can be a child of another sub-theme, and it can be branched and organized however you see fit.