Migrating to Drupal 8 part 1: embracing change

Migrating to Drupal 8 part 1: embracing change

When we made the move to Drupal 8, we knew we had to start with a great foundation. Drupal 8 introduces a brand new theming system, something radically different than what was used in Drupal 7. Instead of using PHP templates, Drupal 8 uses the Twig markup language. It’s a welcome and much needed shift that will not only cater to front-end specialists, but users who are not programmers at all.

What we’re going to do in this three-part series is take a run through the setup and configuration of our base Drupal 8 theme, move into Twig and how it works, and finally we’ll talk about some things that we’ve learned after using Twig and Drupal 8 for a few months.

Defining our theme

The first thing we need to do is create a new folder for our theme, and define ourselves an `.info.yml` file inside. Themes in Drupal 8 go inside the `themes` folder within the root directory of your Drupal installation. Let’s go ahead and create our theme directory. This folder must be named the same as your theme. We’re going to call our theme ‘stayClassy’, but feel free to choose a more suitable name for yours.

Now that we have our theme folder, let’s create our `.info.yml` file. This file will tell Drupal what you’re defining, and the properties it contains. The name you assign to this file and where you place it is very specific. The name of the file has to be the same name as your theme, and must be placed within the theme folder at the root of your Drupal installation. Since we’ve named our theme `stayClassy`, inside of our `stayClassy` folder, we will create a `stayClassy.info.yml` file. If your theme name contains spaces, replace those with underscores.

Within the file, let’s add a few key mappings that are required for our theme to function correctly. The four that we absolutely need are `name`, `description`, `type`, and `core`. The `name` key is the name of your theme, `description` is a short sentence describing your theme, `type` describes to Drupal what we’re trying to define (this could be `module`, for example), and `core` defines the version of core that we’re using this for. We’ve also added a couple of optional fields: `screenshot` which is the name of an image file that will function as an image preview of what the theme would look like, and `base theme` which tells Drupal that our theme will be an extension of the core `stable` theme (which means, for example, that if Drupal can’t find a specific template file within our theme directory, it will fall back to the base theme templates). Our `stayClassy.info.yml` file should now look like this:

We now have our own theme! We can actually go into the Admin -> Appearance section of our Drupal install, find our theme and enable it. If you prefer, you can enable the theme and set it to be the default theme through Drush as well (make sure you have Drush 8) using "drush config-set system.theme default theme_name". In our case, `theme_name` would be `stayClassy`.

Importing our libraries

If you go to your homepage you should now see a (mostly) unstyled site! There are probably some Drupal styles being pulled in, but we’ll get rid of those when we add in our own. So let’s do that now! Head back into your `.info.yml` file and let’s add some more keys.

Let’s add in some of our own CSS and JS files. Within our theme folder, I’ll make two new folders: `css` and `js`. Within those folders, we’ll make a `styles.css` and a `scripts.js` respectively.

Now we just have to let Drupal know that it needs to be using these files. We do this by defining a library within a `.libraries.yml` file that we’ll create within our theme folder, and then telling Drupal to include that library within our `.info.yml` file. It’s important to note here that Drupal 8 will only load what you tell it to load, so every CSS or JS file that you need has to be included within a library that’s attached to the theme.

Let’s create our `.libraries.yml` file, and then we’ll look at how we can get Drupal to load our libraries. Create a new file called `theme_name.libraries.yml` in the root of your theme directory.

Let’s now define our global CSS and JS libraries within our new `.libraries.yml` file:

Here we’re defining two libraries, `global-css` and `global-js`, these are going to be included in our `.info.yml` file so that they are added globally across our site. You can see the syntax for each, you first declare the name of the library and then you give it a type. For the `global-css` you can see that we’ve given it a type of `css`, and for the `global-js` we’ve given it a type of `js`. Note that each new line is indented two spaces, not a tab. We then define which files are included in that library using the path to the file. We created these files already, so just add their relative path. If one of your CSS files are specific to print styling for example, you can specify that within the braces: `css/styles.css: { media: print }`. In the case of your JS files, you can also define any dependencies your library might require, in the form of `extension/name`. So if one of your dependencies was another of your own JS files within your theme, you would write `stayClassy/dependency_name.js`. In this case, we’re declaring that jQuery is a dependency, and in Drupal 8 jQuery is in core, but now it’s only loaded when you declare it to be.

Drupal will load all of your CSS and JS in the order of which you define them, and by default it will load all of your JS in the footer. If you need a specific JS library to be loaded within the header, you need to simply add `header: true` to your library definition:

If you need to, you can also include externally hosted libraries by declaring the asset as `type: external`. For example, let’s say we wished to include the Angular library within our theme, we would add it like so:

We define the path to the file as the URL, and then add the `type: external` within the braces. Including external CSS libraries works the same way.

Including our libraries

Now that we have our libraries defined, we need to include them within our theme, and there are two ways to do this: we can include them globally so they are loaded on every page, or we can include them specifically with a template so they are loaded only on pages where that template is used. Let’s include our libraries globally, and then we’ll look at how we include them on the template level. Head back to your `.info.yml` file and add in a `libraries` key mapping:

We’ve now included our `global-css` and `global-js` libraries. I’ve also included the `normalize` library, which is now in Drupal core.

I mentioned that we can also include a library on the template level, but we’ll get to that once we start talking about the templates themselves.

Removing core styling

If you head back to your homepage you should now see that our libraries are being included. You might also see that Drupal is loading some core stylesheets, however we don’t want these, we want to only use the styles we write. Luckily we have an easy way to remove these; head back into the `.info.yml` file and use the `stylesheets-remove` key:

We now have our theme defined, and our assets included within it, which means we’re ready to start building our site! In the next post in our series we’ll start defining the regions our pages will contain, and then we’ll look at making some templates to define the various components that we’ll place in those regions.

Read part 2

Read part 3