This document discusses theming in Drupal 8. It covers: - What theming is and how themes override default module outputs - Creating a theme and selecting a base theme like classy or stable - Using Twig templates to define HTML and preprocess functions - Declaring libraries for asset loading and managing dependencies - Defining breakpoints and configuration options for the admin interface - Registering new theme hooks and template files

1. Drupal 8 Theming
Deep Dive
Romain JARRAUD @romainjarraud

2. Romain JARRAUD
Trainer/consultant
Trained People
romainj on d.o

3. What is theming?

4. Theming?
Functionnal Display
Drupal and modules Theme

5. Theming?
• THEMING = HTML output
• Other outputs could be RSS feed, JSON…
• HEADfull Drupal 8 here!

6. Theming?
• Modules produce datas.
• Modules have default renderings.
• For example, Block module define
block.twig.html template to render each block.
• The theme OVERRIDES the default renderings.

7. Theming?
Theme overrides defaults:
• html code for every element on the page.
• styles: font size, colors, images...
• effects using javascript.

8. Theme
Browser CSS
Templates
Drupal &
modules Content
HTML
Web Page
Request

9. The menu
• Theme creation.
• Template.
• Asset management.
• Breakpoints.
• Configuration form.
• External configuration.
• Declaration of our own template file.

10. Create a theme

11. Create a theme
/themes/ive/ive.info.yml

12. Base theme
• Theme inherits from its parents.
• Drupal 8 provides 2 base themes:
• classy - for those who loves having
lots of html code.
• stable - for the others.

13. Classy vs. Stable
/core/themes/stable/templates/block/
block.html.twig
/core/themes/classy/templates/block/
block.html.twig

14. Theme files

15. Templates

16. TWIG
• Drupal 8 uses TWIG.
• TWIG created by Fabien Potencier.
• Templating system to generate HTML.

17. • Template name .html.twig: example
of page.html.twig for the page
template.
• They hold the HTML tags along with
TWIG code.
TWIG

18. TWIG (quickly)
• Display the content of var: {{ var }}.
• Display any kind of variable (string, array, object): {{
node.title }}.
• Function: {% if var %} {% endif %}.
• Comments: {# comment #}
• Translation:
• {% trans %} translatable {{ string }} {% endtrans %}.
• Ready to be translated through Drupal UI!

19. TWIG (quickly)
•Filters:
•{{ date|format_date(‘medium’) }}
•string:
•Escaping: {{ text }} (default).
•No escaping: {{ text|passthrough }} (be carreful!).
•Placeholder : {{ text|placeholder }}.
•{{ content|without(‘links’) }}.
•{{ string|lower }} (upper as well).
•{{ class_name|clean_class }}.
•{{ id_name|clean_id }}.

20. TWIG Debug
Activate Twig Debug in local environment by
editing the file /sites/default/services.yml.

21. • Not enough because Drupal caches entity rendering.
• Uncomment the loading of a local.settings.php file
in /sites/default/settings.php.
TWIG Debug
That file adds a cache backend render service which avoid
Drupal to cache.

22. Template suggestions
• Depending on context you can ask
Drupal to load a specific template.
• For example to display a node Drupal
uses node.html.twig. But it can use
node--article.html.twig (if it exists!)
for any node of type article.

23. • A module defines suggestions with
hook_theme_suggestions_HOOK().
• Other modules or themes can add
suggestions with
hook_theme_suggestions_alter() or
hook_theme_suggestions_HOOK_alter().
Template suggestions

24. Template suggestions
(Those comments are shown
thanks to TWIG Debug mode)

25. Template override
• Copy original file into theme template folder.
• Rename it if necessary.
• Empty theme registry.
• Do what you want!

26. Preprocess
functions

27. Preprocess functions
Template
Default
preprocess
$variables
Theme
preprocess
$variables
Modules
preprocess
$variables

28. Called functions order
Theme suggestions
• MODULE_theme_suggestions_HOOK(array $variables)
• OTHERMODULE_theme_suggestions_alter(array &$suggestions, array
$variables, $hook)
• OTHERMODULE_theme_suggestions_HOOK_alter(array &$suggestions, array
$variables)
• THEME_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
• THEME_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)
Preprocess
• template_preprocess_HOOK(array &$variables)
• OTHERMODULE_preprocess(array &$variables, $hook)
• OTHERMODULE_preprocess_HOOK(array &$variables)
• THEME_preprocess(array &$variables, $hook)
• THEME_preprocess_HOOK(array &$variables)

29. Librairies

30. Librairies
• No more manually asset loading.
• Bye bye drupal_add_css(),
drupal_add_js() and
drupal_add_library()!
• Must add any asset through a library.
• Drupal takes care of libraries loading
and dependencies.

31. Librairies
Declaration Loading

32. Libraries declaration
/themes/ive/ive.libraries.yml

33. Loading from /themes/ive/ive.info.yml
Libraries loading

34. Libraries loading
Loading from a template file
/themes/ive/templates/node.html.twig

35. Loading from /themes/ive/ive.theme using
THEME_page_attachments_alter()
Libraries loading

36. Loading from /themes/ive/ive.theme using a
preprocess fonction
Libraries loading

37. Library dependency
• No javascript loaded for anonymous users.
• Dependencies should be explicit.
/themes/ive/ive.libraries.yml

38. Libraries override
/themes/ive/ive.info.yml

39. Libraries extension
/themes/ive/ive.info.yml

40. From PHP to JS
/themes/ive/ive.theme
/themes/ive/js/ive.js

41. Breakpoints

42. Breakpoints
Breakpoints are exposed on the server side.
For example, images can be loaded
depending on those breakpoints.

43. /themes/ive/ive.breakpoints.yml
Breakpoints

44. Breakpoints

45. Configuration
system

46. Configuration system
• How to add settings in the backoffice.
• Each theme gets its own default form.
• Alter the form with
THEME_form_system_theme_settings_alter()
(using the Form API).

47. /themes/ive/config/install/ive.settings.yml
Defines:
• ive.settings configuration.
• « ive » with its default value « one ».
This configuration is loaded during installation.
Configuration system

48. /themes/ive/ive.theme
Configuration system

49. Configuration system

50. • External configuration files (e.g. image style)
can be integrated into a theme:
• Export files via Drupal UI.
• Clean UUID.
• Place files into /themes/ive/config/optional.
• Those files are only loaded during installation.
Configuration system

51. Adding your own
template

52. Theme hook declaration
• Any theme and module can declare its own
formatting.
• Each theme hook is associated with a
template file.
• Each theme hook got its own preprocess
function (template_preprocess_HOOK()) and
theme suggestions function
(MODULE_theme_suggestions_HOOK()).

53. /modules/simple/simple.module
Theme hook declaration

54. Template file
/modules/simple/templates/simple.html.twig

55. /modules/simple/src/Controller/Simple.php
Theme hook use

56. A few more things…

57. • Everything is a block: breadcrumb, messages…
• Logo format is SVG.
• Utilities modules for themers:
• Libraries UI
• Breakpoints UI
• No more theme functions but templates
instead.
• No more theme() function but Render Arrays.
• No more process functions.

58. Conclusion
Not so many things
to learn compared to Drupal 7.
Better organization for assets
management.
Easier with Drupal 8!

59. Thanks!