Enhanced Drupal templates. Review of the Twig Tweak Module

When using any kind of solution, we usually encounter the need to create generic support functions. A similar situation occurs when working with templates in Drupal 9. If you’ve ever created custom code to display a block, view, or entities in a Drupal 9 template, and are interested in ready-made and tested solution, this article is for you. We’ll show you the Twig Tweak module, which provides a number of support functions.

Twig and Drupal

Twig is a template engine for PHP, released in 2009. It’s constantly developed. As at the date of writing this article, the latest version is 3.4.1. Twig is an integral part of the Symfony framework, and thus – also of Drupal 9. Drupal in its own way implements certain concepts, such as entities, blocks, and views. To build the final HTML from the so-called render arrays, Drupal uses internal classes designed for this purpose. Twig, however, doesn't know by default how they work. Because of this, it’s natively impossible to, for example, render a block or view with any parameters and in any place just by using the Twig engine. To make such an operation possible, the Drupal community has created the Twig Tweak module, which introduces a substantial list of Twig extensions addressing the most common Drupal-specific problems.

Twig Tweak module

The module was released on 3 January 2016, and its latest update was on 15 April 2022. Twig Tweak has an older version that is compatible with Drupal 8 and 9, and a newer one that requires Drupal 9. For obvious reasons (using Symfony from version 8), the module doesn't have a Drupal 7 version.

The Twig Tweak module provides a collection of extensions for Twig that allow you to, for example, render views, blocks, regions, entities, fields, menus, forms, tokens, and more. The full list of possibilities is provided in the Twig Tweak cheat sheet prepared by the authors.

Twig Tweak is currently used by over 100 thousand websites. The latest 3.x version is gaining in popularity over the older 2.x version, which is experiencing slight but continuous drops.

 

Source: Drupal.org

The creator and the main person maintaining the module is the user Chi. Due to the popularity of the module, the full list of people who contributed to its development is too extensive to be quoted.

Installation

The Twig Tweak module's installation is standard.

composer require drupal/twig_tweak

drush pm:enable twig_tweak

The module has no dependencies other than Drupal Core and also doesn't provide custom permissions.

There is one configuration option - twig_tweak_enable_php_filter - which is set in the settings.php file. It is set to TRUE / FALSE and is FALSE by default. Enabling this option adds the possibility of using pure PHP in Twig. The option is turned off by default, possibly for security reasons.

How to use Twig Tweak

After installing the module, we get access to the following functions:

drupal_view

Renders the provided view. Example: 

{{ drupal_view(‘view_id’, 'view_display_id’) }}

drupal_view_result

Renders only the result of the provided view. Example: 

{{ drupal_view_result(‘view_id’, 'view_display_id’) }}

drupal_block

Renders the provided block. Example:

{# Block with default configuration. #}

{{ drupal_block('block_id') }}

{# Block with custom configuration. #}

{{ drupal_block('block_id', {config_id: 'foo', another_config_id: false}) }}

{# Block without block.html.twig theming. #}

{{ drupal_block('block_id', wrapper=false) }}

drupal_region

Renders the provided region. Example:

{# Foo region of the default theme. #}

{{ drupal_region(‘foo’) }}

{# Foo region of Bartik theme. #}

{{ drupal_region('foo', 'bartik') }}

Other functions in Twig Tweak

Let's take a look at other options available in this module:

drupal_entity - renders entities,

drupal_entity_form - renders entity form,

drupal_field - renders field,

drupal_menu - renders menu,

drupal_form - renders form,

drupal_image - renders image,

drupal_token - replaces token,

drupal_config - renders configurations,

drupal_dump / dd - renders a readable version of the variable's content (helpful for debugging),

drupal_title - renders the title of the current page,

drupal_url - renders URL,

drupal_link - renders link,

drupal_messages - renders status messages,

drupal_breadcrumb - renders breadcrumbs,

drupal_breakpoint - triggers the Xdebug's breakpoint,

drupal_contextual_links - renders contextual links.

Filters in the Twig Tweak module

Now we'll take a look at the filters available in the tool:

token_replace - replaces token,

preg_replace - enables using the preg_replace function in Twig,

image_style - applies the given image style,

transliterate - transliterates text from Unicode to US-ASCII,

check_markup - filters text based on the text style specified in the system,

format_size - formats the given number of bytes into a character representation with a multiple suffix,

truncate - limits the given text to the chosen number of characters,

view - returns the render array for the given entity or field,

with - works inversely to the core's without filter,

children - used in multiple-selection fields to get a list of items,

file_uri - returns the URI of a given media file,

file_url - enables using the file_url function in Twig,

translation - returns the translation of a given entity,

cache_metadata - adds cache metadata to the printed field,

php - executes the given string of characters as PHP code.

You can find a detailed description of the filters together with examples of use in the above-linked Twig Tweak cheat sheet.

Twig Tweak module - summary

The Twig Tweak module saves time and opens up new possibilities for developers. The filters and functions it provides are useful in everyday work with Twig. The module is very popular, well-supported, and willingly recommended by the community. As a team of Drupal developers, we recommend installing and trying out the possibilities provided by the Twig Tweak module.