Drupal 8's theming layer is complemented by Twig, a component of the Symfony framework. Twig is a template language that uses a syntax similar to Django and Jinja templates. The previous version of Drupal used PHPTemplate that required frontend developers to have a rudimentary understanding of PHP.
In this recipe, we will override the Twig template to provide customizations for the e-mail form element. We will use the basic Twig syntax to add a new class and provide a default placeholder.
This recipe assumes that you have a custom theme created, such as the one you created in the first recipe. When you see mytheme, use the machine name of the theme you created.
- Create a
templatefolder in your theme's base directory to hold your Twig templates. - To begin, you need to copy the
input.html.twigfile fromcore/modules/system/templates/input.html.twigto your theme'stemplatefolder. - Rename the
input.html.twigfile toinput--email.html.twigin order to use the proper theme hook suggestion, as shown in the following screenshot:
- We will use the
addClass twigfunction to add aninput__emailclass:<input{{ attributes.addClass('input__email') }}/>{{ children }} - Above the previous line, we will create a Twig variable using ternary operators to provide a customer placeholder:
{% set placeholder = attributes.placeholder ? attributes.placeholder : '[email protected]' %}This creates a new variable called
placeholderusing the set operator. The question mark (?) operator checks whether theplaceholderproperty is empty in theattributesobject. If it is not empty, it uses the existing value. If the value is empty, it provides a default value. - Go to the Configuration tab and then to Development to rebuild Drupal's cache. We need to do this because Drupal caches the generated Twig output. Any changes made to a Twig template require a cache rebuild.
- View an
emailfield orformelement and find the modification:
Drupal's theme system is built around hooks and hook suggestions. The element definition of the e-mail input element defines the input__email theme hook. If there is no input__email hook implemented through a Twig template or PHP function, it will step down to just input.
A processor, such as Drupal's theme layer, passes variables to Twig. Variables or properties of objects can be printed by wrapping the variable name with curly brackets. All of core's default templates provide information in the file's document block that details the available Twig variables.
Twig has a simplistic syntax with basic logic and functions. The addClass method will take the attributes variable and add the class provided in addition to the existing contents.
When providing a theme hook suggestion or altering an existing template, you will need to rebuild Drupal's cache. The compiled Twig template, as PHP, is cached by Drupal so that Twig does not need to compile each time the template is invoked.
Twig automatically escapes the output by default, making Drupal 8 one of the most secure versions yet. For Drupal 7, as a whole, most security advisors were for cross-site scripting (XSS) vulnerabilities in contributed projects. With Drupal core, using Twig, these security advisories should be severely reduced.
Drupal utilizes theme hook suggestions as ways to allow output variations based on different conditions. It allows site themes to provide a more specific template for certain instances.
When a theme hook has double underscores (__), Drupal's theme system understands this, and it can break apart the theme hook to find a more generic template. For instance, the e-mail element definition provides input__email as its theme hook. Drupal understands this as follows:
- Look for a Twig template named
input--email.html.twigor a theme hook that definesinput__email - If you are not satisfied, look for a Twig template named
input.html.twigor a theme hook that defines the input
Theme hook suggestions can be provided by the hook_theme_suggestions() hook in a .module or .theme file.
Debugging can be enabled to inspect the various template files that make up a page and their theme hook suggestions, and check which are active. This can be accomplished by editing the sites/default/services.yml file. If a services.yml file does not exist, copy the default.services.yml to create one.
You need to change debug: false to debug: true under the twig.config section of the file. This will cause the Drupal theming layer to print out the source code comments containing the template information. When debug is on, Drupal will not cache the compiled versions of Twig templates and render them on the fly.
There is another setting that prevents you from having to rebuild Drupal's cache on each template file change, but do not leave debug enabled. The twig.config.auto_reload boolean can be set to true. If this is set to true, the Twig templates will be recompiled if the source code changes.
The Twig has ternary operators for logic. Using a question mark (?), we can perform a basic is true or not empty operation, whereas a question mark and colon (?:) performs a basic is false or is empty operation.
You may also use the if and else logic to provide different outputs based on variables.
- Refer to the Twig documentation at http://twig.sensiolabs.org/documentation
- Refer to the API documentation for
hook_theme_suggestionsat https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Render%21theme.api.php/function/hook_theme_suggestions_HOOK/8