Articles

Drupal allows you to override all templates used to generate HTML markup, so you can fully control the output markup in your custom theme. There are templates for every part of the page, from the high-level HTML down to small fields.

Overriding Templates

You can override Drupal core templates by adding templates to your theme folder that follow specific naming conventions.

To override templates, you need to:

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.

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: