Drupal 8 Theming Essential Guide

Drupal 8 will soon become the new norm. Enter the “Drupal 8" query in Google Trends, and you will see how D8 has risen with time.

Compared to the previous version, Drupal 8 has made big improvements. There are so many changes in front-end, the theming system in this version. This means some challenges, and awesome new world to try for Drupal themers. Yet, have you got familiar with it? And the fact is there are not many tutorials about Drupal 8 front-end. Struck is what we sometimes feel.

So in this guide, I'll cover basic Drupal 8 theming, including:

  • What's new with Drupal 8 theming?
  • Theme folder structure.
  • Defining a theme with the .info.yml file
  • Libraries - how to add stylesheets & scripts to the theme.
  • Introducing Stable & Classy
  • Theme engine (introducing Twig).
  • Breakpoint module
  • Lastly, you'll create a drupal 8 theme from scratch by following our step by step tutorial.

And by the time you finish the tutorial, you will have a good understanding of the Drupal 8 theming system, and how to create a new theme in Drupal 8, and also a starter theme you'll be able to use in your future projects.

What's new?

I’ll list some changes with the theming system of Drupal 8 compared to Drupal 7. You may have got familiar with these in the Drupal 7 version. The bases are still remained, but they have changed in a new form. There may be some points you don’t understand, but don’t worry. I’ll explain them later. Now just take these as bullet points to remember.

  • Your custom theme now goes into a "theme" directory in the root and not in the "/sites/all/themes"
  • .info files now become .info.yml files that use the YAML syntax
  • PHP template engine is replaced by Twig.
  • All theme files are now html.twig instead of .tpl.php.
  • template.php becomes theme_name.theme.
  • Stylesheets (css) and scripts (js) are defined in libraries.
  • Introducing the 2 new base themes - Stable & Classy.
  • CSS coding standards are based upon two very popular conventions SMACSS and BEM.
  • Drupal 8 is responsive out of the box.
  • Breakpoints can be set and used across modules and themes.
  • And much more

Theme Folder Structure in D8

You used to place all of themes, modules, and third-party library assets like Font-Awesome, jquery,... at the sites/all/themes directory in Drupal 7. So in the past, if you want to create a custom theme, you would place it in /sites/all/themes/{custom/}.

File structure in Drupal 8 has changed. Now, the core folder contains all the modules and themes that are used in Drupal core, and other custom or contributed modules and themes will live in the /modules, and /themes respectively.

To create a custom theme, you will need to place it at /themes/{custom}.

A folder structure for a simple theme would look like this

  • theme_name
    • css
    • images
    • js

Let’s give you an example of a complete theme folder.

The .info.yml file

Drupal will scan the theme directory and search for the theme_name.info.yml file to install your theme. Drupal 8 will look at the .info.yml the same way Drupal 7 looks at .info file. D8 has adopted the Symfony YAML (.yml) format. This is also the format of many programming languages. The pros is that YML uses specific standard which is supported by many libraries.

This is a complete info.yml file of our zircon D8 theme.

      name: Zircon
      type: theme
      base theme: classy
      description: 'A flexible, colorable theme with many regions and a responsive, mobile-first layout.'
      package: Core
      core: 8.x
      libraries:
      - zircon/global-styling
      regions:
        header: Header
        primary_menu: 'Primary menu'
        secondary_menu: 'Secondary menu'
        main_menu: 'Main menu'
        slideshow: Slideshow
        help: Help
        page_top: 'Page top'
        page_bottom: 'Page bottom'
        messages: Messages
        featured: Featured
        breadcrumb: Breadcrumb
        content: Content # the content region is required
        sidebar_first: 'Sidebar first'
        sidebar_second: 'Sidebar second'
        panel_first_1: 'Panel first col 1'
        panel_second_1: 'Panel second col 1'
        panel_second_2: 'Panel second col 2'
        panel_second_3: 'Panel second col 3'
        panel_second_4: 'Panel second col 4'
        footer: Footer

Fields you can find in a *.info.yml file

The following keys are what you might find in a .info.yml file. Note that some are required, some are optional. They will provide meta-data about your theme, and its basic functionality.

  1. name (required)

    This is the name of your theme. The name will show up in the administration/appearance D8 admin
  2. description (optional yet recommended)

    What you want to describe about your theme should be put here. This will also appear in Administration/Appearance
  3. version (optional )

    The version of your theme. It will show behind the theme name.
  4. type (required)

    Let Drupal know the type of extension. E.g. Theme, Module, or Profile.
  5. core (required)

    Show the major version of Drupal core that is supported
  6. base theme (optional yet recommended)

    Indicate what base theme your custom theme will inherit. If not include this field, Drupal will use Stable as your base theme.
  7. region (optional)

    Define the regions of the blocks that can be placed. If you do not declare any regions in the .info.yaml file, Drupal will take the regions enabled by core. Keep in mind that if you define the regions even just one, the default regions are not longer applied. And content region is required to exist if you define regions in the info file.

Adding regions to your theme

A region is basically a section on the page of your theme. You can define as many regions as you wish on your .info.yml file. And the next step you have to update your page.twig file to inform the new regions.

Regions are rendered in the page template file, which will be covered in the next recipe, Twig templates.

Libraries

You may have asked where can I add stylesheets (CSS) and script (Javascript) to my theme? In D8, the answer is the libraries file.

In Drupal 7, you would include all of your stylesheets & scripts of your theme in the .info file as follows:

theme.info

      name = zircon
      description = 'A flexible, recolorable theme with many regions and a responsive, mobile-first layout.'
      core = "8.x"
      ; Stylesheets
      stylesheets[all][] = css/style.css
      stylesheets[print][] = css/print.css
      ; Scripts
      scripts[] = js/scripts.js

Now, in Drupal 8 you have to include in both the theme_name.info.yml & theme_name.libraries.yml to enable the stylesheets, and scripts. Here are what they look like.

theme_name.info.yml

      name: Zircon
      type: theme
      base theme: classy
      description: 'A flexible, recolorable theme with many regions and a responsive, mobile-first layout.'
      package: Core
      core: 8.x
      libraries:
      - zircon/global-styling

theme_name.libraries.yml

      Global-styling:
          css:
            Theme:
              css/style.css: {}
              css/print.css: { media: print }
          js:
              js/scripts.js: {}
          dependencies:
          - core/drupal
          - core/jquery

In other words, in D8, if you define a library in the .libraries.yml file, you have to declare it in the .info.yml file respectively. Drupal 8 takes this approach to create the new library file in order to improve website performance. Rather than loading all CSS, JS and other assets, only those that are specified in the library are loaded.

With the example, in the .info file, we define a library called global-styling. Global-styling means that this library will be included on every page. And in the library file, we indicate the css, and js file that will load with the global-styling library. The css and js that loads globally will live in root/theme/css/style.css and root/theme/js/scripts.js respectively.

Dependencies

Libraries have the ability to choose other libraries as dependencies. This is to help Drupal know what is necessary to load.

You notice that we have dependencies: core/jquery. By default, Drupal 8 does not load any scripts. Jquery is not included sidewide like in Drupal 7. So we have to inform to include the Jquery version of Drupal core. And we also define core/drupal dependencies to take advantage of Drupal.behaviors

How to add Libraries to selected pages

What if you only want your libraries to be enabled to specific pages? Let's say you want to add the style to your maintenance page. So the first step is to define the css for it in your .libraries.yml file:

      maintenance_page:
        version: VERSION
        css:
          theme:
            css/maintenance-page.css: {}

After that, instead of attaching it globally in your .info.yml file, we'll have to add some codes to the THEME_NAME.theme in your theme folder (if you don't have one, you need to create one and place it in the root of your theme folder)

Here’s how it would look like:

      function zircon_preprocess_maintenance_page(&$variables) {
        if ($variables['is_front']) {
        $variables['#attached']['library'][] = ’zircon/maintenance_page';
        }
      }

If you have other library with other name, change the correct respective name as shown in the screenshot above.

Remember to clear your cache to see it works.

Introducing two new base themes - Stable & Classy

Base themes are said to be used as a backwards compatibility layer for Drupal 8's core markup, CSS and JS.

The reason is if you don’t use a base theme ( by setting base theme : false in the .info.yml file), Drupal will use the markup in core. If there are changes in core, you need to check the core markup or you run the risk of losing your style. That’s terrible. Meanwhile, if you use base theme, markup will reside in the markup folder of your base themes. Change anything if you want, and never fear risk.

So the use of base themes is to ensure the stability of your theme.

Besides Bartik, Seven, and Stark, which you may have seen in Drupal 7, 2 new base themes are introduced in D8 - Stable & Classy.

The chart below will show you the relationship among the core themes

Stark

Core ⇒ Stable

Classy ⇒ Seven

⇒ Bartik

As indicated Seven & Bartik themes will use Classy as its base theme.

When no base theme is informed in the .info.yml file, Stable will automatically become one.

With the coming of Classy, and Stable, this is really helpful as Drupal gives you 2 flavors to choose as base theme.

Stable: minimal markup and very few classes
Classy: provide default markup with sensible classes for styling

If you want to start with some markups and a few defined classes , go with Classy. This base theme provides a solid markup and css combinations built on modern BEM conventions that you will find easier to work with.

If you want to start with more clean theme markups, and want to add your own classes, you can choose Stable. And in fact, it’s the default base theme in D8.

Let’s show the differences in markup of the 2 themes when viewing source-code.

Classy

      <div class="region field-name-field-cars field--type-string field--label-above">
        <div class="field__label">Cars</div>
        <div class='field__items'>
          <div class="field__item">BMW</div>
          <div class="field__item">Mercedes</div>
          <div class="field__item">Honda</div>
        </div>
      </div>

Stable

      <div>
        <div>Cars</div>
        <div>
          <div>BMW</div>
          <div>Mercedes</div>
          <div>Honda</div>
        </div>
      </div>

See how minimal the Stable theme is in comparison with Classy.

Twig Templating

Twig is the template engine for PHP. It is a component of the Symfony framework. In D8, Twig becomes the default templating engine (which was PHP engine in Drupal 7). As a result, all of the theme_* functions and PHPTemplate *.tpl.php files are no longer used. The template files now have a new Twig extension:

*.html.twig

With Twig, people say that Drupal 8 has moved away from an isolated island. Twig is meant to be more modern,

more secure, easier to use ( No more PHP codes inside your template files. PHP engine requires users to have a rudimentary knowledge of PHP to use. Now non technical users will find Twig much more easier to use) and well-documented.

Syntax

Twig syntax is similar Django and Jinja templates, and it’s quite simple:

{{ These }} are for printing content, either explicitly or via functions

{% These %} are for executing statements

{# These #} are for comments

Twig Filter

It's possible to let the variable go through a filter before printing it. This can be done using
{{ variable|filter }}.

A complete list of default Twig filters can be found here.

Adding theme regions with Twig

Theme developers don’t want to be limited with the default regions of Drupal 8. So defining regions is an inevitable task for any themers.

The first step is to declare the regions you want to add in the .info.yml file. Say that I want to add header, main content, footer. and sidebar. I will go back to the info file, and add these.

      #Define regions
      regions:
        header: 'Header'
        content: 'Main Content'
        sidebar: ‘Sidebar’
        footer: 'Footer'

But this is still not complete. It is because Drupal’s standard html template doesn’t know about your custom regions. So the next step is to copy the page.html.twig file from the core templates folder and place it in a folder named templates within your theme (if you don’t have this folder you have to create one)

Now provided that we want to add the sidebar to your page first, here are the codes:

      {% if page.sidebar %}
        {{ page.sidebar }}
      {% endif %}

The above codes creates a conditional to check that the header region has something in it, then prints out the content. This is a good practice to ensure that empty markup will not be printed to the page.

The content section is an exception. It does not need a conditional statement because there will always be something in the content region.

Repeat the codes for other regions of your page.

      <div class="page">
        {% if page.header %}
           <header>
            {{ page.header}}
           </header>
        {% endif %}
          <main>
          {{ page.content }}
        </main>
        {% if page.sidebar %}
        <div id="sidebar">
           {{ page.sidebar }} 
        </div>
        {% endif %}

 

{% if page.header %} <footer> {{ page.header}} </footer> {% endif %} </div>

Twig Debug

How do we know what template file that we need to override, how to know which template file that renders a page or a markup when you view source?

To do that, Twig in Drupal 8 has come with a very useful function - Twig Debug.
Here how to enable it.

Under the twig.config section, you need to change debug: false to debug: true (If there is not services.yml here; make a copy of the default.services.yml file and rename it to services.yml). And when inspecting the page, you see that Drupal will print out the source code comments that indicate the template information

Debug variables

You can print a variable, or all variables in the template file with the dump() function. The syntax is really simple.

// Print out all variables on the page.

{{ dump() }}

// Print content of the foo variable.

{{ dump(foo) }}

The Breakpoint module

This is a new cool feature in Drupal 8. Breakpoints are used to separate the resolutions (height & width) of devices so that you will have a responsive design that will change corresponding to each device being used.

To create new Breakpoints, you need to add a [theme-name] or [module-name] .breakpoints.yml in the root folder of your theme or module

We’ll take the bartik.breakpoints.yml to show you an example of the content of the breakpoint file.

      bartik.mobile:
        label: mobile
        mediaQuery: '(min-width: 0px)'
        weight: 0
        multipliers:
        - 1x
      bartik.narrow:
        label: narrow
        mediaQuery: 'all and (min-width: 560px) and (max-width: 850px)'
        weight: 1
        multipliers:
        - 1x
      bartik.wide:
        label: wide
        mediaQuery: 'all and (min-width: 851px)'
        weight: 2
        multipliers:
        - 1x

Here’s the explanation.

  • label - A human readable label for the breakpoint. It should be unique within the file
  • mediaQuery - Media query for the breakpoint
  • weight - Weight used for ordering breakpoint
  • multipliers - the ratio between the physical pixel size of the active device and the device-independent pixel size. This is used to support pixel resolution multipliers. E.g. 1x is normal; 1.5x supports Android; 2x supports Mac retina device.

Let’s go back to the breakpoint file. we have divided 3 different breakpoints for the bartik theme (mobile, narrow, and wide) with different widths. And from mobile to wide (small width to larger width), the weight increases (0 - 2). This is also how Breakpoints order the weight based on width or height.

If you use SASS for styling, you will find that Breakpoints help your styling much easier and simpler.

Conclusion

That’s it for theming. I hope that until now you have got fundamental knowledge about Drupal 8 theming. Next, you can create your own base theme by following our next post - Step to step to create a Drupal 8 theme from scratch.

If you have a question regarding about themes, theming, or anything you read here, feel free to leave a comment below, or do it via our contact page. We are always free to help.

Share