Building a custom theme in Drupal 8

Based on the Classy base theme

Presentation by Anne Tomasevich

Introduction

This is the part where I talk about myself

Agenda

• What's changing?
• Let's make a theme
• Twig basics and debugging

Let's start from the very beginning

What is theming?

- Someone who's good at being very general

Why would you use Drupal 8 now?!

Let's build this thing

What am I totally glossing over?

• template.php *.theme
• Grid framework and CSS architecture
• Probably a lot of other things

Create a theme folder

• Drupal core now resides in its own folder. Contributed and custom modules and themes are in the modules and themes folders, respectively.
• Don't forget to create a custom folder for your custom theme!

Create a .info.yml file

# mappy.info.yml
name: Mappy
type: theme
description: 'D8 Theme for a basic leaflet site.'
core: 8.x
base theme: classy
libraries:
 - mappy/global-styling
 - mappy/leaflet
regions:
  navbar: 'Top Navigation Bar'
  content: Content # required!
  sidebar: 'Sidebar'
  footer: 'Footer'
					

[theme-name].info becomes [theme-name].info.yml

Dot info dot what?

• YAML is a data serialization language.
• Key-value pairs.
• Check out Symfony's excellent writeup on YAML syntax before getting started.
• And mind your whitespace!

Create a .info.yml file

# mappy.info.yml
name: Mappy
type: theme
description: 'D8 Theme for a basic leaflet site.'
core: 8.x
regions:
  navbar: 'Top Navigation Bar'
  content: Content # required!
  sidebar: 'Sidebar'
  footer: 'Footer'
					

This looks familiar, right?

Classy, a new base theme

# mappy.info.yml
base theme: classy
					

• In D8, default classes are stripped from Drupal core and moved into the base theme Classy.
• To avoid these default classes, simply don't base your theme on Classy.
• But we want them because BEM is awesome! Check out this awesome introduction.

Libraries

# mappy.info.yml
libraries:
 - mappy/global-styling
 - mappy/leaflet
					

• In D8, assets can be added in a few different ways: globally, per-template, per-page, and more.
• All libraries must be defined in your *.libraries.yml file.

Create a .libraries.yml file

# mappy.libraries.yml
global-styling:
  css:
    theme:
      css/styles.css: {}

leaflet:
  css:
    theme:
      css/leaflet.css: {}
  js:
    js/leaflet.js: {}
    js/map.js: {}
  dependencies:
    - core/jquery
					

Note that jQuery is listed as a dependency of the Leaflet library. Since jQuery is no longer loaded automatically on every page, it must be explicitly required.

Adding assets to your site

# mappy.info.yml
libraries:
 - mappy/global-styling
 - mappy/leaflet
					

• Since this is a small site and we need our libraries on every page, we're adding them globally.
• Visit drupal.org for more information on methods for adding assets.

Create a .breakpoints.yml file

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

Ours is stolen adapted from the Bartik theme.

Breakpoints

• Once you add a .breakpoints.yml file (and uninstall and reinstall your theme), the breakpoints you've set will be exposed in the admin UI.
• These breakpoints can be used across various modules.

With these files set up, we now have a working custom theme!

Template files

• In our theme's current state, we're using Classy's default template files.
• If we want to override them, it's time to learn some Twig.

If one more person makes a "Gettin' Twiggy with it" joke...

Intro to Twig

• Twig is a template engine with syntax similar to Django, Jinja, and Liquid.
• It simplifies template creation with clean syntax and useful built-in filters, functions, and tags.
• In a Drupal template file (now with the extention .html.twig), anything between curly braces is Twig.

Twig delimiters

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

{% These %} are for executing statements

{# These #} are for comments

Printing variables and regions

In D7 we render content like so:

<?php print render($page['sidebar']); ?>

Printing variables in D8 is as easy as including them inside double curly braces:

{# In page--front.html.twig #}
{# Print the sidebar region. #}

  {{ page.sidebar }}
					

Printing variables with special characters

If a variable name contains special characters, use Twig's subscript syntax (which will look familiar to seasoned Drupalers).

{# In page--front.html.twig #}
{# Print the page type. #}

  {{ page['#type'] }}
					

This will come in handy more during debugging.

Filters

Twig comes with many built-in filters that variables are passed to via the pipe character.

Here's the date filter:

	{# Format the post date. #}

  {{ post.published|date("Y-m-d") }}
					

Drupal-specific filters

Check them out here.

Remember our old friend t()?

	{# Run an ARIA label through t() #}

  <nav class="tabs" role="navigation" aria-label="{{ 'Tabs'|t }}">
					

Functions

Twig also comes with various functions that can be used in double curly braces.

Here's the cycle function doing some very important work:

{% set fruits = ['apple', 'orange', 'banana'] %}

{% for i in 0..10 %}
    {{ cycle(fruits, i) }}
{% endfor %}
					

Tags

Used for control flow and other fun things.

{# From Bartik's page.html.twig #}
{# If there are tabs, output them. #}

  {% if tabs %}
    
      {{ tabs }}
    
  {% endif %}
					

In template files, we’ll use the if statement quite often.

Get psyched

Make sure you check out the Twig coding standards!

Twig debugging

To enable debug mode and turn off caching, we need to do 3 things:

You do NOT need turn off Twig caching - turning on auto reload is enough.

Use settings.local.php

if (file_exists(__DIR__ . '/settings.local.php')) {
  include __DIR__ . '/settings.local.php';
}
					

Turn on debug mode and auto reload

Check out settings.local.php

// In settings.local.php

/**
 * Enable local development services.
 */
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
					

This tells us to head over to development.services.yml.

// In sites/development.services.yml
parameters:
  twig.config:
    debug: true
    auto-reload: true
					

Turn off Drupal's render cache

Just kidding, you already did.

// In settings.local.php

/**
 * Disable the render cache (this includes the page cache).
 *
 * This setting disables the render cache by using the Null cache back-end
 * defined by the development.services.yml file above.
 *
 * Do not use this setting until after the site is installed.
 */
$settings['cache']['bins']['render'] = 'cache.backend.null';
					

Debug away

Now you can:

• View HTML comments in your browser’s code inspector with lots of helpful info:
  • Which theme hook is being implemented
  • Theme hook suggestions (i.e. how to override the current theme hook)
  • Which template file is being output.
• Make changes to your source code and simply refresh the page to see your changes rather than constantly rebuilding the cache.

dump( )

With Twig debugging turned on, we can use the Twig function dump().

{# In a template file #}
{# Print out all variables on the page. #}

  {{ dump() }}


{# Print the page's base path. #}

  {{ dump(base_path) }}
					

Even better: kint( )

Install the Devel and Devel Kint modules to use kint() in the same way, but with a pretty, expandable array instead.

{# In a template file #}
{# Print out all variables on the page. #}

  {{ kint() }}
					

Resources and further reading

• A brilliant blog post about D8 theming (Savas)
• D8 theming guide (Sander)
• YAML formatting (Symfony)
• Intro to BEM (CSS Wizardry)
• Adding assets to pages (drupal.org)
• Twig documentation (Sensiolabs)
• Drupal-specific Twig filters (drupal.org)
• Twig coding standards (drupal.org)
• Twig debugging and devel (drupalize.me)

Questions?