- 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.
- Default theme implementation to display a forum. May contain forum containers as well as forum topics. Available variables: forums: The forums to display (as processed by forum-list.html.twig).; topics: The topics to display.; topicspager: The topics pager.; forumsdefined: A flag to indicate that the forums are configured.; See also.
- Flexible: Twig is powered by a flexible lexer and parser. This allows the developer to define its own custom tags and filters, and create its own DSL. What makes Twig better than PHP as a template engine? When it comes to template engines in PHP, many people will tell you that PHP itself is a template engine.
Let's get started by installing our web environment that we will be using as we take an exciting look at Drupal 8 theming with Twig. Installing an AMP (Apache, MySQL, PHP) stack To install and run Drupal 8, our server environment must meet and pass certain requirements.
Joris Snoek/ Drupal Developer
Last month we implemented a user story for our Drupal distro OpenLucius: we needed to send clean html from Drupal 9 modules. This should also be scalable, as in: different modules should be able to mail different content in a consistent template. After some time of coding and trying different modules and options within those modules, we finally got it together in a nice, clean and scalable way.
So I thought more people would like to send nice html mails from Drupal 8/9 programmatically: I extracted the code and produced an isolated example module, even installable.
Copy and run off
I published it here on Github, so you can copy it and run off with it to do whatever you need. At the moment it's not a published Drupal.org project with all kinds of configurable stuff.
Install instructions
Clone this repo and install it like a custom module in Drupal; I haven't set it up with Composer / Packagist. The drupal module has a dependency on Swiftmailer module, which has a dependency on the Mailsystem Drupal module. After you installed it, these three modules should be enabled:
- Lucius HTML mail example
Config instructions
Configure Mailsystem
Head to /admin/config/system/mailsystem and copy this config:
- Formatter: choose 'Swiftmailer'
- Sender: choose 'Default PHP Mailer', somehow it didn't work when I choose 'Swiftmailer' here. That took a loooong time to figure out.
- Choose your active theme (custom or contrib), this is needed so Swiftmailer will detect your clean html Twig override for the emails:
Copy Twig template override
Copy the file 'swiftmailer--lucius-html-mail.html.twig' to your custom theme's '/templates' folder. This is the clean html email template override which Swiftmailer will use later on and you can tune anyway you like.
Swiftmailer config
FYI, all 'Transport settings' in Swiftmailer config can be left to default (see /config/swiftmailer/transport).
Explaining the Drupal code
1. hook_mail() in .module file
First of all, to make use of the Drupal's mailing system: you need to implement hook_mail in the .module file:
- Get global site name -and email.
- This took a loooooooooooooooooooong time to figure out, but you need to define these headers to make Drupal html mails work.
- Additional parameters to fill Twig html email template.
2. Custom Drupal Mail Service 'lucius_html_mail.mail'.
I implemented a custom Drupal Service 'lucius_html_mail.mail', for among other things scalability: this service handles all generic stuff for email sending, while other modules can use this service via Dependency injection and send mails with different parameters: message content in this case.
- Define our custom Mail Service and inject 2 external Services.
- Constructor to facilitate the 2 external Services.
- Build the mailing variables, loop through users, get name and email, finally send mails.
3. Drupal Route and Controller to test and send example emails
I defined a route '/send_test_mail'. If you head over to that url in your browser, the code in sendTestMail() will execute.
If all is ok: all users will receive the example mail.
!) So make sure you're testing this in an environment where mails can't go to the outside world, we use local Docker with Mailhog for example. (!
- Drupal's Dependency Injection in action: inject our custom Service 'lucius_html_mail.mail'.
- Prepare all paramaters for the mail with static example texts. Then send the mails via our Service method 'sendMail()'.
- Simple helper function to get all users.
So, if you head over to '/send_test_mail', all users should receive an email that looks like this:
4. Custom Twig override file 'swiftmailer--lucius-html-mail.html.twig'
As mentioned earlier, swiftmailer--lucius-html-mail.html.twig should be copied somewhere to your custom theme's /templates folder. I found this html code in this open source repo. It's even responsive and uses a lot of inline styles, needed to make it compatible to all major email clients.
As you can see, there are Twig variables, mostly I use the values in the $message array. These variables match the parameters we build earlier. Fine line songbook chords. Function Lucius_html_mail_mail() (hook_mail) turned our parameters into one $message array, which can be used in the Twig template as shown in above image.
So tune this template anyway you like, or implement a complete new one with other variables. Apache tomcat v9. It's all in your hands now, make it the way you want in a clean, responsive and scalable way!
Handy: Twig template file override suggestions
Drupal 8 Twig Include
If you turn on Development mode in Drupal, you can see all template suggestions to go even further down/up the road:
Wrap up
Ok, that's it for now. Hopefully you're now able to implement nice clean emails for your Drupal 8/9 system. If you need more explanation, or you can't get it to work: please let me know.
When starting to work in Twig, one of the first things you're going to want to do is enable Twig debug and two key development modules.
As with Drupal 7 debugging, you'll want to enable the Devel module right away. This will give you access to dpm and dsm functions to dig through available variables during debugging and site building. In Drupal 8 however, there is an additional module included in the Devel install called Kint.
Finding variables with Kint
Kint is very useful in Twig templates. You get all the available variables through dpm and dsm, plus all available methods—which is super handy for pulling in pieces from referenced entities. Methods reach can into other entities to pull fields, labels, and other useful information. Methods can also rewrite the variable output to format it in different ways or access array pieces. After you turn on Twig debugging, you can find variables by using {{ kint() }} inside your template.
Devel also has a nice cache clear function that will clear both the site cache and the image cache. Drupal 8 can be difficult when it comes to displaying image styles on a local environment—especially with responsive images. Devel cache clear will get your images displaying properly.
Twig Documentation
Twig debugging to get template suggestions
Enabling debugging is very easy in Drupal 8. Every D8 site comes with a default.services.yml file in the sites/default folder. Copy this file and rename it to services.yml ( and make sure you either .gitignore it or assume-unchanged, since you don't want your debugging settings to be pushed to anywhere except your local machine).
Last month we implemented a user story for our Drupal distro OpenLucius: we needed to send clean html from Drupal 9 modules. This should also be scalable, as in: different modules should be able to mail different content in a consistent template. After some time of coding and trying different modules and options within those modules, we finally got it together in a nice, clean and scalable way.
So I thought more people would like to send nice html mails from Drupal 8/9 programmatically: I extracted the code and produced an isolated example module, even installable.
Copy and run off
I published it here on Github, so you can copy it and run off with it to do whatever you need. At the moment it's not a published Drupal.org project with all kinds of configurable stuff.
Install instructions
Clone this repo and install it like a custom module in Drupal; I haven't set it up with Composer / Packagist. The drupal module has a dependency on Swiftmailer module, which has a dependency on the Mailsystem Drupal module. After you installed it, these three modules should be enabled:
- Lucius HTML mail example
Config instructions
Configure Mailsystem
Head to /admin/config/system/mailsystem and copy this config:
- Formatter: choose 'Swiftmailer'
- Sender: choose 'Default PHP Mailer', somehow it didn't work when I choose 'Swiftmailer' here. That took a loooong time to figure out.
- Choose your active theme (custom or contrib), this is needed so Swiftmailer will detect your clean html Twig override for the emails:
Copy Twig template override
Copy the file 'swiftmailer--lucius-html-mail.html.twig' to your custom theme's '/templates' folder. This is the clean html email template override which Swiftmailer will use later on and you can tune anyway you like.
Swiftmailer config
FYI, all 'Transport settings' in Swiftmailer config can be left to default (see /config/swiftmailer/transport).
Explaining the Drupal code
1. hook_mail() in .module file
First of all, to make use of the Drupal's mailing system: you need to implement hook_mail in the .module file:
- Get global site name -and email.
- This took a loooooooooooooooooooong time to figure out, but you need to define these headers to make Drupal html mails work.
- Additional parameters to fill Twig html email template.
2. Custom Drupal Mail Service 'lucius_html_mail.mail'.
I implemented a custom Drupal Service 'lucius_html_mail.mail', for among other things scalability: this service handles all generic stuff for email sending, while other modules can use this service via Dependency injection and send mails with different parameters: message content in this case.
- Define our custom Mail Service and inject 2 external Services.
- Constructor to facilitate the 2 external Services.
- Build the mailing variables, loop through users, get name and email, finally send mails.
3. Drupal Route and Controller to test and send example emails
I defined a route '/send_test_mail'. If you head over to that url in your browser, the code in sendTestMail() will execute.
If all is ok: all users will receive the example mail.
!) So make sure you're testing this in an environment where mails can't go to the outside world, we use local Docker with Mailhog for example. (!
- Drupal's Dependency Injection in action: inject our custom Service 'lucius_html_mail.mail'.
- Prepare all paramaters for the mail with static example texts. Then send the mails via our Service method 'sendMail()'.
- Simple helper function to get all users.
So, if you head over to '/send_test_mail', all users should receive an email that looks like this:
4. Custom Twig override file 'swiftmailer--lucius-html-mail.html.twig'
As mentioned earlier, swiftmailer--lucius-html-mail.html.twig should be copied somewhere to your custom theme's /templates folder. I found this html code in this open source repo. It's even responsive and uses a lot of inline styles, needed to make it compatible to all major email clients.
As you can see, there are Twig variables, mostly I use the values in the $message array. These variables match the parameters we build earlier. Fine line songbook chords. Function Lucius_html_mail_mail() (hook_mail) turned our parameters into one $message array, which can be used in the Twig template as shown in above image.
So tune this template anyway you like, or implement a complete new one with other variables. Apache tomcat v9. It's all in your hands now, make it the way you want in a clean, responsive and scalable way!
Handy: Twig template file override suggestions
Drupal 8 Twig Include
If you turn on Development mode in Drupal, you can see all template suggestions to go even further down/up the road:
Wrap up
Ok, that's it for now. Hopefully you're now able to implement nice clean emails for your Drupal 8/9 system. If you need more explanation, or you can't get it to work: please let me know.
When starting to work in Twig, one of the first things you're going to want to do is enable Twig debug and two key development modules.
As with Drupal 7 debugging, you'll want to enable the Devel module right away. This will give you access to dpm and dsm functions to dig through available variables during debugging and site building. In Drupal 8 however, there is an additional module included in the Devel install called Kint.
Finding variables with Kint
Kint is very useful in Twig templates. You get all the available variables through dpm and dsm, plus all available methods—which is super handy for pulling in pieces from referenced entities. Methods reach can into other entities to pull fields, labels, and other useful information. Methods can also rewrite the variable output to format it in different ways or access array pieces. After you turn on Twig debugging, you can find variables by using {{ kint() }} inside your template.
Devel also has a nice cache clear function that will clear both the site cache and the image cache. Drupal 8 can be difficult when it comes to displaying image styles on a local environment—especially with responsive images. Devel cache clear will get your images displaying properly.
Twig Documentation
Twig debugging to get template suggestions
Enabling debugging is very easy in Drupal 8. Every D8 site comes with a default.services.yml file in the sites/default folder. Copy this file and rename it to services.yml ( and make sure you either .gitignore it or assume-unchanged, since you don't want your debugging settings to be pushed to anywhere except your local machine).
Drupal 8 Twig Functions
In that services.yml file (around line 39) is a parameter called twig.config. Techsmith camtasia how to videos. Change the debug variable to true, auto_reload to true, and the cache variable to false. Save and clear cache. You should now be able to use your browser's inspector to tool to see all the possible template suggestions in the code as well as which templates are being used. This is equivalent to the drush vset theme_debug 1 command in D7.
