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 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 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: Drupal 10 uses Twig 3.x. (Drupal 9 uses Twig version 2.x and Drupal 8 uses Twig version 1.x. Be sure to use the appropriate version when consulting Twig's official documentation.
Drupalize.Me resources
Frontend Theming
Guide
Making Drupal fast by default implies having caching layers and CSS and JavaScript aggregation utilities enabled out-of-the-box. As a theme developer this can be annoying, because you must clear these various caches in order to preview any changes. In addition, inspecting variables with debugging tools often produces PHP errors. We'll make some recommendations for PHP settings on your local environment that can prevent these errors from happening so often.
By the end of this tutorial, you should be able to:
- Set up your local Drupal site for theme development
- Prepare your local development environment for working on and debugging themes
Before you can create a path or link to another page on your site, you'll need to know the route (unless there is already a variable available for the URL you need). Finding a route can be a tricky task unless you have the right tools. In this tutorial, we'll show how tools like Webprofiler, Drush, and Grep can be used to get route information for a page, so that you can use functions that need a route as a function parameter.
In this tutorial we'll:
- Learn how to determine the route or path of an internal page.
By default, individual forms in Drupal are not output using Twig template files. It's possible to associate a form with a Twig template file by creating a new theme hook, and then referencing that theme hook from the $form array that defines the form. Doing so allows theme developers to customize the layout of the elements in the form using HTML and CSS.
This is useful when you want to change the layout of the entire form. For example, putting the elements into 2 columns. If you want to change individual elements in the form, you can often do so by overriding element specific Twig template files.
In this tutorial, we'll:
- Learn how to create a new theme hook that can be used to theme an element in a render array.
- Associate the
$formwe want to theme with the new theme hook we created. - Create a Twig template file for the theme hook that will allow us to lay out the form elements using custom HTML.
By the end of this tutorial, you should be able to associate a Twig template file with any form in Drupal, so that you can customize its layout using HTML and CSS.
Related tutorials
Using Twig's attach_library function, you can attach asset libraries of CSS or JavaScript files. Learn more about asset libraries, or jump straight to the relevant section on attach_library in Attach a Library.
External resources
- Twig 3.x Documentation (twig.symfony.com)
- 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 (twig.symfony.com)
- This document describes the syntax and semantics of the template engine and will be most useful as a reference to those creating Twig templates.
- Twig coding standards (twig.symfony.com)
- Recommended coding standards for Twig that you should use in your Drupal Twig template files.
- Twig in Drupal (Drupal.org)
- Guide to community-contributed documentation on Twig as it is used in Drupal.
- Use the Upgrade Status module to check your Twig files for deprecated syntax use.
- Twig updated from 2.x to 3.x (Drupal.org)
- Note especially changes to
spacelesssyntax and the removal of support forifinside aforclause.
- Note especially changes to
- Deprecated features in Twig 2.x (twig.symfony.com)
- This page from Twig's official documentation lists all of the deprecated features in Twig 2.x, which were removed in Twig 3.x.
- Twig debug support in PhpStorm: Blog and Documentation
Twig helper modules
- Twig Tweak (Drupal.org)
- Twig Tweak provides a Twig extension with functions and filters that can improve the developer experience.
- Twig Field Value (Drupal.org)
- Twig Field Value helps frontend developers access field data in render arrays, bypassing the need for creating new variables in preprocess functions.
- Twig Extensions (Drupal.org)
- Provides additional Twig filters for localization of dates and currency, as well as a few miscellaneous utilities.