Drupal loads templates based on specific naming conventions. This allows you to override templates by adding them to your theme and assigning specific names.
After adding a template, you must rebuild the cache so that Drupal can detect your new template.
About Twig
Twig is a compiled template language based on PHP. When your web page is rendered, the Twig engine takes the template and converts it into a "compiled" PHP template, which is stored in a secure directory at sites/default/files/php/twig. Compilation happens once, template files are cached for reuse, and recompiled when the Twig cache is cleared.
The Drupal Twig initiative shares the same motivation as Symfony’s: to introduce a modern, powerful, object-oriented engine that allows developers to properly focus on Drupal.
When working with a Twig template file, most variables are documented in the file’s comments. However, when they’re not, or when themes or modules introduce new variables, we need a way to discover all available variables within the template scope. Twig provides the dump() function for inspecting variables in templates.
The dump() function will not output anything unless debugging is enabled. Learn how to enable Twig debugging.
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.
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: