This document discusses how to use Twig templating in Drupal to facilitate complex styling, layouts, and behaviors without advanced PHP knowledge. It explains that Twig templates allow adding, removing, and modifying HTML elements through logic-layered templates. Further, Twig can complement and extend Drupal configurations, and in some cases hardcode static content. Specific examples demonstrate adding attributes and conditionally including content. The document concludes that Twig is a powerful tool that should be used responsibly.

1. Twig in the Wild
Jeremy Koulish
August 24, 2018

2. Twig in the Wild
Jeremy Koulish
August 24, 2018
How to Work Drupal Templating Magic
Without Being a PHP Wizard

3. Why Twig?

4. Before Drupal 8, Drupal templates were PHP
Which looks like PHP.
node.tpl.php from D7 Bartik theme

5. In Drupal 8, markup looks more like HTML
With some PHP-ish logic layered on top.

6. How to Twig

7. Using Twig
1. Create a custom theme piggybacking off a base theme
(usually “Classy” theme from core).
2. Trigger custom overrides by using specific filenames
within your custom theme’s “templates” folder.
• Those filenames are automagically determined and
prioritized by Twig.

8. Life-saving Twig helper modules
Twig Debug
helps properly name and scope Twig overrides
sites/development.services.yml Local site’s browser devtools

9. Life-saving Twig helper modules
Twig Tweak
Loads of useful helpers, including content structure printing.
https://www.drupal.org/docs/8/modules/twig-tweak
Any Twig file Your browser

10. That’s all nice…..
but what can you DO with Twig?

11. Three Major Use Categories
1. Facilitate complex styling, layout and/or behavior by
directly manipulating markup structure.
2. Complement and extend Drupal configuration
3. Hardcode static content directly into the code base
when content cannot – or should not – be edited by
future content creators
•

12. Use Type #1: Facilitate Complex
Theming and Behavior

13. Facilitate Complex Theming and Behavior
Add a wrapper element
DEFAULT
CUSTOMIZED
Default template from paragraphs module
Default paragraph template - USWDS contrib theme

14. Facilitate Complex Theming and Behavior
Remove a wrapper element
DEFAULT CUSTOMIZED
Default region template from classy base theme region—sidebar-first.html.twig (demo site)

15. Facilitate Complex Theming and Behavior
Change a tag name
DEFAULT CUSTOMIZED
Default field template from classy base theme field--paragraph--field-title.html.twig (demo site)

16. Facilitate Complex Theming and Behavior
Add attributes to an element
DEFAULT CUSTOMIZED
Default USWDS paragraph template paragraph.html.twig (demo site)

17. Facilitate Complex Theming and Behavior
• Conditionality
• Loops
• Content manipulation
• Filters
• Set new variables
• Access Drupal-supplied variables
Insert PHP-style logic for dynamic templating

18. Facilitate Complex Theming and Behavior
Add attributes to an element
DEFAULT
CUSTOMIZED
paragraph.html.twig (demo site)
paragraph—basic-text.html.twig (demo site)

19. Use Type #2: Complement and
Extend Drupal Configuration

20. Complement/Extend Drupal Configuration
Editing display config through view modes can get very
complicated, very fast.

21. Complement/Extend Drupal Configuration
“Alert box” paragraph
uses config-
generated values to
specify type of box,
matching USWDS
specs.
paragraph--alert-box.html.twig

22. Use Type #3: Hardcode Content
Directly Into the Template

23. Hardcode Content Directly In the Template
• Hard for content creators/editors to parse.
• Not completely WYSIWYG in complex cases.
• Easy to delete content or internal markup, but much
harder to recover it.
• It already deviates from the Drupal Way.
Because sometimes, a WYSIWYG box just won’t cut it.

24. Hardcode Content Directly In the Template
Example: official US government site banner

25. Hardcode Content Directly In the Template
government-banner.html.twig in USWDS contrib theme

26. Hardcode Content Directly In the Template
Only hardcode content if you don’t
expect it to change anytime soon.
Or ever.

27. Conclusion
There is no one right way to Twig……but it’s a powerful tool.
USE IT RESPONSIBLY!

28. Resources
Twig Documentation:
https://twig.symfony.com/doc/1.x/
Twig Tweak docs:
https://www.drupal.org/docs/8/modules/twig-tweak
Presentation demo code:
https://github.com/jkoul/twiginthewild
Presentation demo site:
LINK TBD

29. Thank You!
jeremy.koulish@bixal.com
http://kouli.sh
http://www.bixal.com