Topic

Twig

Last updated September 1, 2017

Twig is a template engine for PHP, which is the language used in Drupal. Twig can be used for templates in generic PHP applications as well as Drupal 8 themes. The Drupal implementation of Twig is the same as regular Twig with a couple of Drupal additions. Drupal adds some custom filters and automatically handles the render pipeline for you. Anything you can do in regular Twig you can also do in Drupal's implementation of Twig.

Example tasks

  • Customize markup in templates for a Drupal 8 site
  • Use dynamic data from variables within template files
  • Customize markup in PHP applications that use Twig for templates

Confidence

Resources on this page use both generic PHP applications as well as template files from Drupal 8 themes for context and examples. The Twig that is used in generic PHP applications can be used in Drupal templates as well. Note that Drupal has extended Twig and provides some Drupal-specific filters and functions. In some cases, these Drupal-specific functions or filters are preferable to their generic Twig counterparts.

Note that Drupal 8 currently uses Twig version 1.x, while Drupal 8.4 is slated to use Twig version 2.x (issue here). Some Twig features differ between these versions.

Drupalize.Me resources

  • Twig in Drupal
    • In this tutorial, you will learn about the role that Twig now plays in Drupal, how Twig impacts the theming experience, and where to find additional resources for learning Twig.
  • Twig Syntax Delimiters
    • Recognize each of Twig's 3 syntax delimiters in Drupal template files (*.html.twig).
  • Arrays and Objects in Twig
    • Know how to access array keys with and without special characters in a Drupal template file using Twig.
  • Loops and Iterators in Twig
    • In this tutorial, you'll learn how to use the for tag to iterate over an array, use the loop variable inside of a for loop for additional context, and various alternative syntaxes for looping over variables in Twig templates.
  • Print Values from a Field with a For Loop
    • In this tutorial, you'll learn how to output values from a multi-value field in an unordered list and add first and last classes to the first and last items in a list by using the Twig loop variable.
  • Twig Filters and Functions
    • In this tutorial, you'll learn about Twig functions and filters, how to use them in a Twig template file, and all about Drupal-specific filters and functions along with their use cases.
  • Whitespace Control in Twig
    • Understand and apply appropriate methods for controlling whitespace in a template file with Twig.
  • Make Your Theme Translatable
    • In this tutorial, you'll learn how to use the t filter and {% trans %} tag in a Twig template, the differences between these two approaches, and how to determine which one to use, and how to translate strings assigned to variables in preprocess functions using the Drupal's PHP t() function.
  • Classes and Attributes in Twig Templates
    • In this tutorial, you'll learn how to add and remove classes from elements in a Twig template, all about the the attributes object, and examples of common tasks using various helper methods on the attributes object
  • Routes, URLs, and Links in Twig Templates
    • Learn about an advanced use case where you need to create links to content outside of the template's scope.
  • Twig Template Inheritance
    • Learn how to reduce code duplication in your theme and understand how Drupal themes utilize Twig's block and extends tags.
  • Twig Templating
    • Learn all about the Twig templating engine and how to use it in the context of a generic PHP application. Concepts learned here also apply to Drupal 8 Twig template files (just without the Drupal-specific tags, filters, and functions).

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • Twig 2.x Documentation (twig.sensiolabs.org)
    • Official documentation for Twig. Contains a reference for tags, filters, functions, and tests, as well as information for template designers and developers looking to extend Twig with custom functionality.
    • Twig for Template Designers
      • This document describes the syntax and semantics of the template engine and will be most useful as reference to those creating Twig templates.
  • Twig in Drupal 8 (drupal.org)
    • Guide to community-contributed documentation on Twig as it is used in Drupal 8.