Articles

To make Drupal 8 theming as performant as possible and provide more flexibility in Twig templates, follow these best practices:

The general idea in Drupal 8 is that you want to avoid generating HTML directly in the PHP code of your custom module. Instead, you want this to go into Twig templates. To create new Twig templates in your module, follow these steps.

Step #1: Define hook_theme in your .module file
Create a [module].module file if it doesn’t already exist, and add the code that defines each of your Twig templates. The key of each item in the array is what you will need to call the template later. Do not use dashes in the file name.

Twig templates can be extended using the following syntax:

{% extends 'html.twig' %}

For more details, see https://symfony.com/doc/current/templates.html#template-inheritance-and-layouts

Sub-themes, like any other theme, differ in one key way: they inherit resources from their parent theme. There are no limitations to the chaining capabilities connecting sub-themes to their parents. A sub-theme can be a child of another sub-theme, and it can be branched and organized however you see fit.

Classy is a core theme in Drupal 8 and the base theme used by Bartik and Seven. The HTML markup found in Classy (and its subthemes) includes CSS classes structured similarly to the BEM and SMACSS naming conventions.

Although the BEM/SMACSS-style naming conventions developed in Classy are very effective and offer many conveniences, they may not suit every project. Those not interested in Classy’s CSS classes can choose a different base theme.

Document all CSS class selectors present in the Classy theme of Drupal 8 RC 2.

format:

.foo { }
.foo-bar { }

filename.html.twig / filename.css

Twig - Available CSS selectors in the Classy theme:

LAYOUT

Body

.user-logged-in { }
.path-frontpage { }
.path-[root_path] { }
.node--type-[node_type] { }
.db-offline { }
.visually-hidden { }
.focusable { }
.skip-link { }

file: html.html.twig
 

Drupal has a powerful image management system that allows the creation of image styles, which can apply various effects to an image and generate derivatives from the original image. This functionality can be used in themes that want to include a default set of image styles designed to work with the theme, rather than relying on those provided by core.

The process of including an image style in your theme is similar to the process of including default configuration in a module.

Many developers prefer to store header/footer code in a separate file and include that file in page.html.twig.

Process

Let’s say you’ve created the following file in your theme’s folder for the header:

THEME_NAME/templates/includes/header.html.twig

And now you want to include this file in:

page.html.twig

Recommended Method

The proper method for Drupal 8 themes is to use Twig namespaces to reference the current theme’s "templates" directory. Here’s an example:

Many Twig templates will have one or more Attribute objects passed in as variables. The purpose of the Attribute object is to store a set of HTML attributes, providing developers with helpful methods for interacting with this data and making it easy to print attributes. For example, attribute.addClass('myclass') makes it easy to add a class without worrying about precise string concatenation.

Typically, attributes in a template should look like this:

As in Drupal 7, you can influence the output of specific HTML using preprocess functions. For example, if you want to add a class to a menu and prefer to do it at the PHP level, you can. This is a good way to alter theme-related markup, but if you're making changes unrelated to the theme, it's better to write a custom module.

(Note: For documentation purposes here, “mytheme” is your theme’s machine name; for example, “bartik” is the machine name for the Bartik theme.)

To work with preprocess functions: