October 26, 2016

Here is one more time about theming in Drupal 8. This article describes basics of how the presentation layer works in Drupal 8 so it’s mostly intended for beginners. You’ll learn what a theme and Template Engine are and how the presentation layer works in D8. If you don’t have any experience with Drupal 8 this article will be useful for you.

Probably you already came across such word as Theme. Let’s take a definition of this term from Drupal.org: “A theme is a collection of files that define the presentation layer“. I absolutely agree with this definition, but frankly speaking it’s not clear enough for people who are beginners in Drupal. Which files define the theme? What do all these files do? Files are css, js, fonts, various libraries, templates - everything that make your site beautiful and user-friendly. Drupal uses template files placed in the theme for HTML markup generation. So the theme is responsible for how your site looks.

Now we have a general idea about what the theme is in Drupal, let’s go further and figure out what Template Engine is. Template Engine is a software which allows to use HTML templates for generation of complete HTML document. The main purpose of template engines is to set apart the presentation layer from a logic. Frequently it’s necessary for parallel work of back-end and front-end coders. Also, a usage of template engines makes your code easier to read and maintain. In a picture below we can see a diagram that illustrates how the template engine works.
Template engine scheme
Data and template are passed into Template Engine where the magic happens, as a result, we have a complete dynamically generated HTML-page. OK, everything is clear with that, but how does Drupal know what template should be used and when? Everything is handled through a theme() function, every piece of HTML is rendered via theme() function. So any module which has a need to make some HTML definitely has an implementation of a hook_theme(). This hook makes a connection between the data and the templates. Shortly, this hook tells Drupal which template should be used and what data should be passed to this template.
Theme function
Here is an example of implementation of hook_theme() in a custom module. One of the theme function named 'my_username' is defined In function mymodule_theme(). All variables required to a successful execution of this function are also listed in that function. Let's take a look at the template my-username.html.twig. Here we can see HTML code mixed with Twig syntax, we've already seen something similar in PHP Template files in D7 or in any other templates of various template engines. So, if we need to generate a chunk of output somewhere we should call this theme function theme_myusername() and pass all defined variables: a ‘name’ and an array with tag attributes.

This template is very simple, made only to show you how it looks. As you can imagine there could be a lot of other templates which are more complex than this one. Of course, we can make our custom template complex and big, but the bigger the file is, the harder it is to read and maintain. Let's take a look at this picture:
Here we can see how the page is rendered and which templates are used for that. If you use your imagination you can see a content area and a sidebar - very simple page structure, we've seen a million such pages in the web. This picture explicitly shows what template is used in the exact region. For example, html.twig.html: it's a very small file which has only 2 tags in it: head and body, the main tags that are presented on every HTML page. But in the body tag, there is a line of code that prints out a variable {{ page }}. In this variable we have an output made by function theme_page(). Do you follow the idea? We have a long list of nested templates, where output of one is passed as a variable inside another. From html.twig.html to field.twig.html and even deeper. Due to that, we have a lot of little templates files which are short, logical, readable and a structure of all these files is very clear.

We know now that all theme functions are defined in modules and all templates are laying there. Does it mean that I have to search through all modules where the template I need is defined each time I need to edit something? It doesn’t look like a separation of the presentation layer from logic. Don’t worry: Drupal took care of you and made all these things clear and easy to use and understand. There is such a thing as a system of overrides in Drupal. What does it mean? It means that Drupal allows you to override all templates that are defined in theme functions and are used for printing out the HTML. So you can have a full control of markup that rendered in your Drupal site.
A connection between Drupal core and the custom theme
Also, there is such a thing in Drupal as a 'base theme'. If you have an experience with D7 theming you may know something about sub-themes. For example, in D7 you could make a sub-theme based on any other theme: make a sub-theme from Bartik, Seven, etc. It means that all template functions, templates, and CSS & JS files from the parent theme will be used in the sub-theme. The same approach is used in Drupal 8 but with significant differences. Yes, there is an inheritance mechanism like in D7. But unlike D7 you cannot create a theme in Drupal 8 without setting a base (parent) theme. By default, we have 2 base themes in core: Stable and Classy. In the picture below you can see a diagram of how templates from Drupal Core are overridden by base themes and inherited/overridden by well-known Bartik and Seven themes.
How templates from Drupal Core are overridden by base themes
What's the main purpose of these base themes? Why I cannot just make my new theme from scratch like in Drupal 7? The answer is obvious: to separate logic from the presentation. With a usage of base themes, you have only one place where aggregated and overridden templates are defined in the Core. So you don't need to go to the files structure and spend your precious time to search for the template you need. What’s the difference between Stable and Classy? The following image clearly illustrates this difference:
A difference between Classy and Stable
With Classy theme you'll have a classes-enriched HTML markup, very similar to the markup generated in D7. So you have all necessary classes which make work of a CSS coder very comfortable. But if you need to have full control on the markup generated on your project, you can use a theme Stable as a base theme. A markup generated by Stable theme doesn't contain any classes, it just as clean and simple as possible. You have to add classes by yourself when you need. We may say that Stable is an advanced level of theming and Classy is easier and more friendly.

Now you’ve got an idea how the presentation layer works in Drupal 8: we’ve learned what template engine is, templates and theme functions are and how theme functions can be defined. We've learnt about template overrides, what the basic theme is and what basic themes we have out of the box. I hope all this gave you an idea of how all these things are set in Drupal 8.

Was this article helpful? Click to rate: 
Average: 4.9 (8 votes)

You may also like

Table of contents Introduction OOP in Drupal 8: what differs Drupal...
Table of contents Preface Security principles Key security objects...
Over the past few years, e-commerce has transformed how people buy...