Twig is the default template engine for Drupal. If you want to make changes to the markup that Drupal outputs you're going to need to know at least some Twig. In this tutorial, we will outline the role that Twig now plays in Drupal, how Twig impacts the theming experience, and where to find additional resources for learning Twig.
At the end of this lesson, you'll be able to:
- Describe the role that Twig plays in creating Drupal themes
- Explain how Twig impacts the theming experience in Drupal
- Locate additional resources for learning Twig
To read a Twig template file, you'll need to recognize Twig's syntax delimiters. Twig has three syntax delimiters: one for printing out variables, another for performing actions or logic, and lastly, one for comments, also used for docblocks.
In this tutorial we'll:
- Explore each of Twig's 3 syntax delimiters.
- Show examples of each from Drupal's core template files.
By the end of this tutorial you should be able to recognize each of Twig's syntax delimiters and understand what the engine will do when it encounters them.
Twig has a special syntax for accessing array keys and objects, also known in Twig as variable attributes. In this tutorial, we'll cover the period or dot (.
) operator to access a variable attribute, as well as subscript or square-bracket syntax, useful for when the key of the array contains special characters, like a dash (-
) or pound sign (#
). We'll also look at the logic Twig uses to find the matching attribute in an array or object.
Many of the variables that you have access to inside of a Twig template file are arrays. For example a list of values for a multi-value field, or a set of error messages generated when validating a form submission. In order to work with arrays in Twig you'll need to understand how for
loops work. This is essential information for anyone creating Drupal themes.
In this tutorial we'll cover:
- Using the
for
tag to iterate over an array - Using the
loop
variable inside of afor
loop for additional context
The ability to loop over an array of values in a Twig template and print out each value individually is an important skill for anyone developing themes for Drupal. Common scenarios include: loop over the values of a multiple value field; iterate through a list of links; and display error messages at the top of forms. This tutorial will provide an example of using the Twig for
function to iterate over a list, or a subset of a list.
In this tutorial we'll cover how to:
- Output values from a multi-value field in an unordered list.
- Add first and last classes to the first and last items in a list by using the Twig
loop
variable.
By the end of this tutorial you should be able to print out the values of an array as individual list items using a loop in Twig.
In Twig, you can modify variables using functions or filters. Twig has a bunch of built-in functions and filters. Drupal extends Twig to provide a few handy Drupal-specific functions and filters as well.
In this tutorial, we'll look at:
- What are functions and filters?
- How to use functions and filters in Twig
- Detailed information about the Drupal-specific functions and filters and their use case
In order to ensure that all user interface strings in your application can be translated using Drupal's localization system, any text you add to templates needs to use either the t
filter or the {% trans %}
tag. Anyone creating themes or editing template files associated with a theme or a module should know how to use these two utilities.
In this tutorial we'll look at:
- How to use the
t
filter and{% trans %}
tag in a Twig template - The differences between the two, and how to determine which one to use
- How to translate strings assigned to variables in preprocess functions using the PHP
t()
function
Theme developers often need to add or remove classes and other attributes from an HTML tag. Template files handle this with a special attributes object that contains the attributes and their values, as well as a handful of powerful methods to help manage these attributes.
In this tutorial we’ll cover:
- Adding/removing classes from elements in a Twig template
- The attributes object
- Examples of common tasks using various helper methods on the attributes object
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.
More often than not, templates in a theme share common elements: the header, footer, sidebar, or more. In Drupal, themes created with a Twig template can be decorated by another one. This template inheritance allows you to build a base "layout" template that contains all the common elements of your layout defined as blocks. A child template can extend the base layout and override any of its defined blocks. This helps prevent code duplication, and keeps your theme more organized.
This tutorial is for theme developers who want to reduce code duplication in their themes, or anyone seeking to better understand how Twig template inheritance works. We'll cover:
- What the Twig
block
andextends
tags do - An example use-case for template inheritance
- How to extend a Twig template from another theme or module
- How to include other Twig templates
The available dynamic tokens or variables vary from template to template. Each "page" is built from and uses many different templates. In this exercise, we'll continue our template overriding practice by overriding the node template. We'll override it and rename it in such a way that it will only affect article nodes on our Drupal site. We'll practice the process of overriding the template, inspecting the available variables, and customizing the markup. Along the way, we'll practice using the Twig filter without
. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Override the node.html.twig template file and target only Article nodes.
- Modify the template so that the content of the image field of a node is output wrapped in a
<div>
independent of the rest of the node's content.
Example:
Note: At the end of this exercise, you'll find a video walk-through of the solution.
In this exercise, we'll continue our template overriding practice by overriding the main menu template. We'll override it and rename it with a file name suggestion so that it will only affect the main menu component of our Drupal site. We'll consult the Bootstrap documentation and add the classes from the base nav component into our overridden main menu template file. Along the way, we'll utilize a variety of methods for adding CSS classes to HTML selectors including using attributes.addClass()
and set
. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Override the menu.html.twig template file, using a file name suggestion to target only the main menu.
- Add CSS classes from the base nav component in Bootstrap.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
In this exercise, we'll continue our template overriding practice by overriding the image field template. We'll consult the Bootstrap documentation and add a responsive image class that will apply to any images uploaded by a user to the field_image
field. Once again, we'll add this class to the classes
array in the set
Twig tag. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Override the image field template file.
- Add values to the
classes
array withset
.
Note: At the end of this exercise, you'll find a video walk-through of the solution.
In this exercise, we'll practice using the t
fiter in a Twig template. As a best practice, all hard-coded text in a template should be translatable. Simple text (containing no dynamic tokens) can be be passed through the t
filter to achieve this objective. Along the way, we'll also use a basic conditional if
statement with Twig. You should work on the exercise steps below first, and you can refer to the video if you need some help.
If you want to try and accomplish this on your own first you'll need to:
- Add a
<div class="label label-warning">
element to the article node template file that contains the string"This node is not published"
. - Use the
t
filter to make the hard-coded text translatable. - Use basic logic statements with Twig to check if the node is published or not.
Note: At the end of this exercise, you'll find a video walk-through of the solution.