Working with theme suggestions

Previously to alter template suggestions, you altered $variables['theme_hook_suggestion'] and $variables['theme_hook_suggestions'] in preprocess functions to introduce theme suggestions. In Drupal 8, modules and themes now define and alter theme suggestions in their own dedicated hooks.

API changes:

Removed the ability to change template suggestions in preprocess functions by altering $variables['theme_hook_suggestion'] and $variables['theme_hook_suggestions'].

New hooks introduced:

Drupal Twig conversion instructions (tpl.php to html.twig)

This document was used during much of the Twig conversion process for Drupal 8 and could be useful to you too for updating your own themes and modules to use the Twig templating engine in Drupal 8.

Note: All Twig work is now being done in the Drupal core issue queue. Only use the Twig conversion sandbox to find previously converted templates and functions.

Steps for Core contributors:

  • Find core issues to post and review patches.
  • Do not apply patches to the sandbox
  • Do not create patches for the sandbox.
  • Only use the sandbox to test and/or retrieve previously converted code.
  • First: Watch this YouTube video for an overview of this process.


First, Clone Drupal 8.x:

git clone -b 8.x d8

The current working version of Drupal will be installed in the folder ‘d8’ (name it whatever you like)

  1. Install Drupal as normal (using the Standard install profile).

Twig and the new theme layer in Drupal 8


Regular meetings

We are organizing our effort via several channels:

  • Weekly Google hangout: Thursdays at 11:30AM PT (2:30PM ET, 20:30 CET). We'll post an agenda and talk about progress and next steps.
  • Chat: #drupal-twig on Freenode. Come join the discussion to ask questions. We hold regular office hours here on Thursdays before and after the call.

Twig best practices - preprocess functions and templates

In order to make Drupal 8 theming as performant as possible and allow for more customization in Twig templates, please follow these best practices:

Return render arrays from preprocess functions

Always return render arrays instead of calling theme() or drupal_render() within preprocess functions.

Comparison of PHPTemplate and Twig theming paradigms

This page compares PHPTemplate to Twig. The Twig effort is currently in progress, so there will be changes and additions to this doc.

For more information, see:

About Twig

Twig is a PHP-based compiled templating language. When your web page renders, the Twig engine takes the template and converts it into a 'compiled' PHP template which it stores in a protected directory in sites/default/files/php_storage/... The compilation is done once. Template files are cached for reuse and are recompiled on clearing the Twig cache.

The Drupal Twig initiative shares the same motivation as the Symfony initiative: to adopt a modern, powerful, OOP-based engine that will allow developers to concentrate on Drupal proper.

1. Doc block


   * @file
   *  File description


   * @file
   *  File description

2. File and function names

PHPTemplate file: node--article.tpl.php

Debugging variables in Twig templates

Twig provides a dump function for debugging variables in templates.

The dump function outputs information about a template variable. The dump function will not display anything unless twig_debug is enabled.

To enable Twig debugging, uncomment the following line in your settings.php (or add it if it's not there):

$settings['twig_debug'] = TRUE;

If your template has a title variable available, the following will dump its contents to your template:

{{ dump(title) }}

To dump all available variables and its contents in a template, add the following to your template:

{{ dump() }}

To dump only the available variable keys use:

{{ dump(_context|keys) }}

There are additional global variables available in all Twig templates:

  • _self references the current template and contains advanced information about a template, i.e. the compiled template class name and information about the Twig environment.


Subscribe with RSS Subscribe to RSS - Twig