Anatomy of a Drupal 8 Theme

Overview of Drupal 8 theming aimed towards beginners or anyone who wants a better idea of what their themers and front-end developer teammates are up to.

This is the text version of a presentation I did at Kansas City’s Virtual Flyover Camp 2020.

What you’ll need

• Beginner understanding of Drupal, like that Blocks, Views, Content Types, and Fields exist.
• General idea of what HTML, CSS, and javascript do.
• When I say ‘configuration’ I mean the choices we make in the admin UI
• I’ll show code blocks as examples, but this isn’t a coding article.

What I’ll cover

1. What is a theme?
2. Base themes and sub-themes
3. Regions
4. File structure
5. Templates
6. Twig
7. Theme Settings

What is a theme?

A theme is a collection of files that define the presentation layer. — drupal.org/docs/8/themeing

When we enter content into the Drupal UI and use the admin UI to configure Content Types and Views, the back end stores and interprets all that. Then the theme takes it and displays it in the browser.

We manage our themes in the Appearance page. We can see what themes are available, which are active, and access the settings for each theme.

What’s in a theme?

• HTML is website content. We can think of Drupal as a nested collection of bits and pieces of HTML we can call components.
• Layout planning. The theme defines Regions, empty boxes for placing Blocks.
• The design. Colors, fonts, form styles, everything.
• Some images. Logos, icons, background images. Whatever is needed to complete the design.
• Digital accessibility heavy lifting. Most HTML and CSS live in the theme, and that’s where a lot of accessibility is done.

What’s not in a theme?

Themes display content based on configuration. Themes do not hold or create content. So these things are not in a theme: content, Views, Blocks, Content Types, Block Types, Taxonomies, etc.

Base themes and sub-themes

Theming core concept: themes inherit and override other themes, from general to specific.

• Core themes do the bare minimum to get content to the browser. No styling, just bare bones. Stable is an example of the core theme.
• Base themes, like Bartik or Olivero, provide the design and layout for all default Drupal things. Base themes are fully designed and may be all you need. Base themes override the core theme.
• Sub-themes add to and alter the base theme. Sub-themes do not stand alone. They are tied to their defined base theme.

Example: If you create a custom Content Type, the base theme may not necessarily style its unique needs. We can use a sub-theme to add additional templates and CSS without directly editing the base theme.

Why not just edit the base theme? If you’re using a contributed base theme like Bartik or Olivero, and those themes get an update, there could be trouble integrating them with your customizations. Sub-themes help us stay organized so we know what’s default and what we’ve changed.

Regions

Theming core concept: Regions are empty containers defined by the theme and used to place content in a layout.

Four empty boxes representing theme regions. There is a header regions and three columns below.

A region is an empty box where we place Blocks via the Drupal admin UI.

The theme has complete control over what regions exist and how they are laid out on the page. One file defines the regions (.info) as a list. Theme templates provide the HTML for the layout with empty space for each region.

We interact with regions in the Block layout page.

File structure

Themes are a collection of files in a folder. Some things must be just so; other things are up to us and can organize as we please.

Drupal theme folder structure on drupal.org

mytheme
  - css (folder)
  - js (folder)
  - images (folder)
  - templates (folder)
  - mytheme.info.yml
  - mytheme.libraries.yml
  - mytheme.theme.yml
  - screenshot.png
  - logo.svg

css, js, images: these folders can be organized however you want.

templates: must be named templates and templates must go here. You can organize your templates into sub-folders.

Theming core concepts: the defining files answer three important questions.

mytheme.info: Who am I?

mytheme.libraries: What do I look like?

mytheme.theme: What makes me special?

Let’s explore each one.

.info

Who am I?

line 1: We name the theme
line 2: Some .info files are for modules. This one is for a theme.
line 6: If this is a sub-theme, link it to a base theme.
line 7: Libraries are collections of CSS and JS files. More later.
line 10: Define my regions.

.libraries

What do I look like?

A library is a group of CSS or javascript files, either built into my theme or called in from an external location. The groups help define their purpose and set their load order.

line 1: I named this group global-styling.
line 10: I named this group global-js.

Look back up at the .info file and see how I added these libraries. The .libraries file makes the libraries. The .info file says to use them.

There is a lot more that can be done with libraries, like loading them in more specific situations.

.theme

What makes me special?

The .theme file is a PHP file used to change Drupal behavior mostly through something called preprocessing where we manipulate (process) Drupal things before (pre) they reach the theme.

Here are some common things I do with it:

1. Make new variables to use in templates. Drupal keeps track of many little pieces of information about our content and configuration. A lot of it has been handily packaged into variables we can use in theme templates. But sometimes we have to dig deeper to get a hard-to-reach bit of information.
2. Hack into HTML that’s hard to get to. Again, most of the time, we have total control over the theme’s HTML via the theme templates, but sometimes a part is so tiny that we have to access it through a preprocess function. I most often do this to add a CSS class to something.
3. Make new theme template suggestions. I’ll cover what this means later, but an example of how I might use this is to be able to make new HTML for a component more specific than the theme would normally look for.

Hey! We’re more than halfway done! Have some water. Relax your shoulders.

Templates — the heart of the theme

1. Templates deliver content from the back end to the front end.
2. Templates interpret configuration to change how content is displayed.
3. Template files are template-name.html.twig and are written with a combination of HTML and Twig.

Without templates, nothing would show up.

Example of a template file: field.html.twig from Stable (core theme). This template covers the display for all fields ever. Let’s have a look.

Everything IN <> brackets is HTML. Everything in {} is Twig. Twig represents dynamic content or configuration.

Notice the if/else statements. On line 45 it asks, “is this field’s configuration set to hide the label?” If so it begins code to show the items in the field without the label. Or else it shows code that includes the label {{ label }}.

So to repeat: the template knows about our content and configuration and can change the HTML accordingly.

Twig

Templating in most content managements systems (Drupal, Wordpress, etc) is done in PHP. Drupal 8 uses Twig which is a template engine, a simpler way to write PHP, simplified in a way that makes it specially suited to theming.

Twig does two things:

1. Show something. Double curly brackets. {{ content }}
2. Do something. Curly plus percent. {% conditionals, functions, etc %}

Look back up at our example template file above. Note the Twig. Note that variables are found in the {{ curly brackets }} to show content.

Nesting templates

Theming core concept: Each component part has its own template, and the content of each template is loaded inside other templates to create the webpage.

A title or field is loaded inside a block. A block is loaded inside a region. A region is loaded inside a page.

Or…

The page has empty spaces for regions. The region holds blocks. Blocks hold their own title and fields.

This is the page template from Bartik. It’s like the wrapper for whole ‘page’. (Not to be confused with the Basic Page content type.) Note the section in blue. The page template is calling for the region template. The region template would, in turn, call for its content, which would be blocks. And so on.

Inheriting and overriding templates

Theming core concept: Templates override each other from general to specific. If there is nothing to override a template, the previous template in the stack will be inherited.

Remember when we talked about how themes override each other? This also happens at a template level.

In this example, these block templates go from general at the bottom for specific on top.

The core theme is the most general. It has a simple template to display all blocks.

The base theme carries the design, so uses its own block template to re-style all blocks. It is doing the same thing as the core block template, so it overrides it.

Additionally the base theme wants special HTML for it’s branding block, so the branding block has its own template. Because this template is more specific to style a specific block, it overrides the more general block template.

Let’s take it up one more level. The sub-theme wants to customize the design of all blocks further. The sub-themes general block template will override the base theme’s general block template, but it is not more specific than the base theme’s branding block template. So even with the sub-theme enabled, the base theme’s branding block template will win.

Naming templates — aka template “suggestions”

Theming core concept: template naming is how Drupal discovers what template to use when, and how Drupal knows when to override.

We must have exactly the right template name for Drupal to know when to use it.

File names are set by Drupal with the template naming system. Naming a file according to the template suggestions tells Drupal when to use it.

Honestly, it can be difficult to find out what these template names are, but if we turn on Twig Debugging, we can see how these suggestions work. When we turn on Twig Debugging, the suggestions are shown in HTML comments.

Template suggestions for the branding block

In this example, there are four template suggestions for the branding block which contains my logo and site name. They start more general at the bottom and get more specific at the top. The x next to block--system-branding-block.html.twig shows which template is being used. So we know that anything below it is more general and being overridden. (It doesn’t necessarily mean those templates exist.) The template above it is more specific. If the more specific template is being used, that one will win.

The last line tells us exactly where the template being used is found. In this case, the template is in a folder called blocks in my sub-theme.

(Something no one ever told me is that debugging tools aren’t only for finding errors and fixing bugs — they’re just general tools that look deeper into the code to see what’s going on. Just saying.)

Template review

• Templates must live in the template folder.
• Templates use variables to show content and use configuration
• Twig does two things: show something and do something
• Component templates are assembled and nested
• Specific template override general templates
• Templates have very specific names to tell Drupal when to use them.

Theme Settings

Okay, last thing.

Theming core concept: themes can have their own options/configuration.

Theme settings apply only to that theme and are entirely created and controlled by the theme. They are usually options to adjust the design or layout. The theme can then use these settings as variables in the templates.

Bartik’s theme settings page

So that’s the crash course on theming! I hope this is helpful as an overview or jumping off point.