Port your Drupal 7 Theme to Drupal 8

Let’s port an existing theme (and subtheme) to Drupal 8. There are quite a few posts out there describing the process, but those mostly cover the creation of a theme rather than its port to D8. To help you out, I’ve gathered most of the relevant information here that helped me achieve a D8 beta version of our beloved theme at Zivtech. You can find a full version of the theme here.

Install Drupal 8

Nothing special here. Download the latest beta and run the install process. You are then going to create a new theme instance and then add D7 components one at a time.

Our Zivtech theme used to be an actual sub theme of Zen. However, there is no D8 release available, and the dev version is broken and unusable at the moment. While I am sure this will change, it was the trigger for us to part from Zen since our D7 was only using some of Zen’s preprocess functions that were easily integrated or left behind.

Create the Folder Structure

First we need to take a quick look at the folder structure. In Drupal 8 our themes go into the “Themes” folder located in the root folder of your Drupal install (themes shipped with core are located in root > core > themes).
I recommend creating both a “contrib” and “custom folder,” and create a folder for your new custom D8 theme so you end up with  root > themes > custom > [yourtheme].

Create the Necessary Files

No .info file anymore. They have been replaced with Twig and Yaml (.yml) files. The syntax is easy and intuitive, but make sure to check out a few examples as there are conventions to respect. For example, set indentation to spaces, not tabs; respect precise indentation, etc). Here is the one I ended up writing:

The first settings are pretty self-explanatory if you’re used to the D7 .info file. The syntax just varies a little. The naming convention is as follows: yourtheme.info.yml

stylesheets-remove, as well as stylesheets-override, are new ways to control some of the stylesheets shipped with core that you may want to alter or remove altogether. I recommend taking a look here to get an overview of overrides and dependencies as they relate to themes and sub-themes when using this function. Additionally, make sure that you have the right paths. You’ll need an absolute path for core files, while you can use tokens for modules and themes css/js. See here for more.

The libraries are a new way to include our styles and scripts in a more modular fashion. In order to reference our inclusions, we need to create a yourtheme.libraries.yml

In our case:

One important thing to notice here is that we need to include jQuery manually as a dependency, which is fair considering a lot of people don’t necessarily need it (Drupal 8 leverages jQuery less than its predecessors). The dependencies function will load things globally BUT you have other options if you wish to include a library on certain parts of your site only (in a template, page, etc).

Example:

In a twig template:

As a preprocess:

You can also set default theme settings as you could before. The settings.php file remains as is in D8 and the functions seem to work the same (I did not have to change anything in my case).

breakpoints: The breakpoints module is now part of core in D8. While we control breakpoints in our stylesheets, we need to make Drupal API aware of what they actually are, so that contrib modules such as picture or responsive image can leverage your theme breakpoint settings. Here is how you would configure it, in a yourtheme.breakpoints.yml.

MediaQuery: Media query text proper ('all and (min-width: 851px)'.

Weight: Positional weight (order) for the breakpoint.

Multipliers: Supported pixel resolution multipliers.
 

You can also create breakpoint groups as shown here.

You don’t need to declare this file in your info.yml files; however you’ll need to clear your caches after adding it.

Templating & Twig

While we all need to learn the Twig syntax, there is one very useful tool to convert your D7 modules and themes to D8. Follow the drush directions from the module’s read-me and see the magic happen. This will not only convert the markup, but also your variables, PHP conditional statements, and so on. While this is not a final version of what I wanted, it showed me quite a bit about twig syntax and I encourage comparing both old and new files to get a good idea about the new twig templating.

Here are a few conversion examples:

html.tpl.php

html.html.twig

page.tpl.php

page.html.twig

node--[content-type].tpl.php

node--[content-type].html.twig

<?php $tags = $content->tags; ?>

{% set tags = content.tags %}

<?php print $tags; ?>

{{ tags }}

<?php if ($content->tags): ?>
<?php endif; ?>

{% if content.tags %}
{% endif %}

<?php if (!empty($content->tags)): ?><endif; ?>

{% if content.tags is not empty %} {% endif %}

<?php if (isset($content->tags)): ?>
<?php endif; ?>

{% if content.tags is defined %}
{% endif %}

<?php if ($count > 0): ?>

<?php endif; ?>

{% if count > 0 %}

{% endif %}

<?php print check_plain($something); ?>

{{ something|striptags }}

<?php print t('Home'); ?>

{{ 'Home'|t }}

More info and examples can be found here.

Here is what our page.html.yml looks like:

Preprocess Functions

Now this is where it gets iffy. twigify will not convert these. It will comment out some of them and mark them as deprecated, but for the rest we’re on our own and have to convert all these manually by finding the right D8 API functions.

Luckily, many of the preprocess functions work similarly to D7. For example, if you need to include an image in one of your page template file, you can still use the page preprocessor function:

On the other hand, for more complex preprocessing there are some changes to keep in mind! For example, in D7 if you were preprocessing a node, and you needed to know its type or its created date, you’d do that like this:

Yet D8 has a major shift to OOP, of course. As a result, we have the introduction of the Typed Data API, which drastically alters how you’d perform the same preprocessing:

Sub Theme

As far as sub theming, not much has changed here. All you need is to include the base theme line in your subtheme yoursubtheme.info.yml

Example:

Resources

You can find a full version of the theme here.

Check out these helpful articles from Drupal.org:

• 27 Questions (and Answers) from My First Drupal 8 Site Build

• Drupal Twig conversion instructions (tpl.php to html.twig)

• Working With Twig Templates

• Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme

• Adding Regions to a Theme