Theming in Drupal 8 with Twig (Part 2)

Following up on the first blog post on Theming in Drupal 8 with Twig, this second part will cover Twig's syntax.

In order to explain these changes more clearly I want to compare the known PHPTemplate syntax with the new Twig template syntax. All examples mentioned in this blog post are based on the latest development state of the Drupal 8 Twig Sandbox.

Usually themers only have to care about the output of predefined variables or simple control structures (if conditions or for loops that output lists of content). Complex logic or further processing of variables should not be placed in the template files - I think everybody can remember a situation in which they inserted a view programmatically in a template or placed custom field on theme layer. In most cases the ability to use custom PHP in template files lead to more complexity and a lack of clarity.

Using variables in templates:

Example for the usage of variables and simple if condition in PHPTemplate:

[gist:5011792:taxonomy-term.tpl.php]

Example for the usage of variables and simple if condition in Twig:

[gist:5011792:taxonomy-term.html.twig]

In the example shown above you can clearly see the differences. Instead of using the PHP'S print function or Drupal's render() function, Twig offers the {{ }} syntax for outputting variables. Twig also improved the output of array and object elements on the theme layer. In the future we will be using the following consistent "point-syntax". Here it does not matter if we want to access array or object elements.

Example of a Views exposed filter in PHPTemplate:
[gist:5011792:syntax.php]

Example of a Views exposed filter in Twig:
[gist:5011792:syntax.twig]

Control Structures

In addition to the already mentioned if conditions there is the possibility to use for loops with the {% %} syntax.

for loop example in PHPTemplate:
[gist:5011792:book-all-books-block.tpl.php]

for loop example in Twig:
[gist:5011792:book-all-books-block.html.twig]

As in earlier versions of Drupal you should avoid putting too much logic in template files. For this purpose you should use the known preprocess function provided by Drupal. Besides the new {% %} syntax in the templates the example also shows the usage of the new nav elements of HTML5 standard, which also has been introduced in other Twig templates.

Comments in templates

For documentation in templates, Twig provides the {# #} syntax.

Example for comments in PHPTemplate (phpdoc style):
[gist:5011792:comments.php]

Example for comments in Twig:
[gist:5011792:comments.html.twig]

Reusability of templates via includes

Even though it was possible to use the PHP include or include_once function for re-using existing parts of a template, it was rarely used in the previous versions of Drupal. In Twig these includes will be used much more often. A good example for the use of includes is the image module - based on the imagestyle another template file will inlcuded by the include function of Twig.
[gist:5011792:image-formatter.html.twig]

With the help of the paramater "with" you can specify variables that are available in the scope of the included template.

Usage of filters in templates

Twig filters offer the possibility to influence the output of variables on the theme level. The following examples show a common use case for filters in Twig - they replace the check_plain function and the t-function with its Twig counterpart.

Translation in templates

Example for translations in PHPTemplate:

Example for translations in Twig:
[gist:5011792:node-admin-overview.html.twig]

As already known from the  t-function you can use placeholders in Twig to make the translatable strings more dynamic. In the example above the variable $votes and type are replaced in the strings.

Escaping special chars in templates

In previous Drupal versions you were able to convert special chars to HTML with the help of the check_plain function.

Example in PHPTemplate:
[gist:5011792:checkplain.php]

Example in Twig:
[gist:5011792:checkplain.twig]

The escape filter can also be used via the alias e and supports parameters for different escape strategies.

• html: escape a string for HTML body context
• js: escapes a string for JavaScript context
• css: escapes a string for CSS context
• url: escapes a string for URI or parameter context
• html_attr: escapes a string for HTML attribute context

Further information on Twig filters can be found in the Twig's documentation.