If you are a front end developer, the biggest takeaway from Dries’s keynote at Drupalcon New Orleans was the Drupal 8 Component based theme initiative. The central idea is that Drupal themes can be structured based on familiar concepts like tabs, menus, forms, headers, etc, rather than Drupal concepts like nodes, blocks and fields.
And this philosophy meshes well with the atomic design approach that has proliferated in the last few years. Pages are not unique entities. Rather, they are entities built up with a system of components. So when we think about design of a site, each page might have the following components:
- Primary Menu
- Secondary Menu
- Footer
- Logo
- Search field
- Social media links
However, the home page might have all of those plus some unique components like:
- Hero container
- Section teasers
We have already started thinking about design in this fashion, so applying these same principles to the organization of a Drupal theme makes a lot of sense.
Drupal-centric theme vs Component-centric theme
Let’s take a look at how a typical Drupal 8 Theme had been structured and then compare that with a component-centric theme. With the old way of doing things the templates, images, stylesheets separate from one another like this:
This is the Bartik theme from Drupal 8.1. There is a templates folder containing twig files for everything: pages, nodes, fields, and blocks. Images and CSS are in their own separate folders.
In a component-centric theme, they would be organized so that items that are specific to a component are grouped together. In this example, the folder contains a components folder with subfolders specific to a component.
In this component, the twig file, scss and images are all contained in the same location. The json file shown here is used to import data into the styleguide. It is important to note that this theme is using the same twig files as the styleguide.
How to create a component-based theme
This might seem like a daunting task, but it’s really not. Drupal recognizes certain twig files like page.html.twig and node.html.twig that sit in the templates directory. How do we get it to use others like components.module-hero.twig?
Twig gives front end developers unparalleled control over the template system. We can use the existing Drupal Twig templates (often called Presenter templates) to point to our component Twig templates using the include tag. We are using the Component Libraries Module to reference twig files that are outside of the /templates directory. Here is a snippet from a page template (/themes/themename/templates/layout/page.html.twig):
The relevant portions are inside the {% include %} tag. This is telling twig to find the file at this location and include it here. Notice that the path is pointing to the theme name following the @ symbol. The “with” statement is adding specific variables to the include. The “only” at the end of the include tag restricts the variables that can be accessed from within the included file. Using “only” prevents the component template from having access to all variables available within the page template. This is useful to avoid variable namespace collisions. So in the example for the footer include only slogan, copyright, footer_items, footer_links and social_links will get included here.
This approach also works hand-in-hand with the BEM (Block Element Modifier) naming convention. The footer.html.twig template looks like this:
All the class names have the block (“footer__”) naming convention so that we have unique identifiers and don’t have to rely on lots of nesting in Sass. And we have made sure that each component is imported in the primary Sass file like this:
Why Component-Based Theming?
The best reason to adopt this approach is maintainability. A front end developer can create a component-based theme, and hand it off to another developer who has little-to-no familiarity with the site (or even Drupal) and it will almost immediately make sense. If the developer needs to fix something in the footer there’s a folder in components that contains everything related to the footer. Same for the header, pagers, and so on. This also allows these same components to be used in JavaScript and mobile apps.
Another reason is the trend toward style guides. If you are already using style guides as part of your design process then you are structuring your files in this way. Combining your style guide and your Drupal theme files in this way provides “a single source of truth.” Making a change to the styleguide means that change will be reflected in the site itself and vice versa.
Component-based Drupal theming will take a little while to master. There will be bumps in the road and we will uncover nuances that are not covered here. Once it becomes a part of your process, it will improve efficiency and maintainability.