Theme development in Drupal 8

Understanding drupal template files

4 min readJun 1, 2018

If you’re asking how Drupal renders the html of your theme, the answer is the template files. They are all named with the extension .html.twig.

This is a new update in D8. Since in D8 Twig replaces PHP engine of D7, all of the tpl.php template files are changed to .html.twig. And these files are placed in the templates folder.

Let’s browse through what each template file functions.

themename.info.yml - defines the theme
themename.theme - programs the themehtml.html.twig - defines every page on the sitepage.html.twig - defines every page on the sitenode.html.twig - defines every node on the siteregion.html.twig - defines every region on the siteblock.html.twig - defines every block on the sitefield.html.twig - defines every dynamic element on the site

Enable Theme Debugging

Just as you can’t successfully build a house without knowing what a hammer is or where to find lumber and materials, you can’t successfully theme a site if you don’t know about its variables, settings and data. To help with this, we will be enabling Drupal’s built-in theme debugging and adding/editing some settings for local theme development.

Create the page.html.twig file

Start with an empty page.html.twig file. Here all of the codes for the body section of your theme are stored. This file contains 3 main elements:

Html markup of your theme.
Region definitions.
Variables for other content items (At the moment, we want it to be basic, so the page.html.twig is for creating regions only)

you can also use the page.html.twig of your core in core\modules\system\templates\page.html.twig for reference, and change this file for your purpose.

Getting Started with Bootstrap in Drupal 8

Before we can begin, go download the Bootstrap theme from drupal.org.

If you use Composer, run the following:

$ composer require drupal/bootstrap

Or Drush,

$ drush dl bootstrap

Once you’ve downloaded the theme go to Appearance and click on “Install and set as default” on the Bootstrap theme.

Create Bootstrap Sub-theme

If you’re going to use Bootstrap on a proper project then it’s recommended you create a sub-theme.

Why Sub-theme?

When you create a sub-theme, the Bootstrap theme will be the “base theme” which means your sub-theme will automatically inherit all templates and assets such as the CSS and JavaScript.

Your sub-theme will automatically use any template from the base theme unless it’s overridden. If you want to modify the page.html.twig then simply copy it from Bootstrap into your sub-theme templates directory and customize. Drupal will automatically pickup the page.html.twig in your sub-theme instead of the one in Bootstrap.

You should never modify the Bootstrap theme. This way you can keep the Bootstrap theme up-to-date.

Bootstrap comes with three starter kits: CDN, Less and Sass. You can see them by going into the starterkits folder in the theme.

Step 1: Create Sub-theme

Let’s now create a sub-theme using the Sass starter kit.

1. Go into the Bootstrap theme and copy the sass folder from starterkits and then paste the folder into /themes/custom.

2. Rename the folder from sass to horizon (you can rename it to whatever you want). Once copied and renamed, the path to the sub-theme should be /themes/custom/horizon In the horizon sub-theme, replace all instances of THEMENAME in the file name to horizon.

Look for the following files:

THEMENAME.libraries.yml => horizon.libraries.yml
THEMENAME.starterkit.yml => horizon.info.yml (NOTE: make sure you change starterkit to info)
THEMENAME.theme => horizon.theme
/config/install/THEMENAME.settings.yml => horizon.settings.yml
/config/schema/THEMENAME.schema.yml => horizon.schema.yml

Open the following files:

horizon.info.yml: Give your sub-theme a name such as “Horizon” and find all THEMENAME and replace them with horizon.
/config/schema/horizon.schema.yml: Find all instances of THEMENAME and replace with horizon.

Step 2: Download Bootstrap

In the above section we just copied a folder and did a find and replace in the THEMENAME string. Now we need to download the actual Bootstrap library and compile the Sass.

Go to the Bootstrap Getting Started page and download the Sass version.Extract the downloaded file into horizon, once extracted the path should be horizon/bootstrap. You may have to rename the folder after it’s extracted.Now we need to copy over the variables in Bootstrap into our Sass files. This will allow us to override the variables without having to modify the actual Bootstrap library.

Go to horizon/bootstrap/assets/stylesheets/bootstrap/_variables.scss and copy the variables into horizon/scss/_default-variables.scss. Paste them just below the $icon-font-path variable.

Step 3: Compile Sass using laravel-mix

We’ll use laravel-mix which is a wrapper on top of webpack. Before you begin make sure you download and install Node.js.

Go into the sub-theme directory and create a package.json, you can do this by running the following command:

$ npm init

Then install laravel-mix with the following command:

$ npm install laravel-mix

In the sub-theme create another file called webpack.mix.js and add the following to it:

let mix = require('laravel-mix');mix.sass('scss/style.scss', 'css/');
mix.options({
  processCssUrls: false
});

Open up package.json and replace the scripts section with the one below:

"scripts": {
  "dev": "NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
  "watch": "NODE_ENV=development node_modules/webpack/bin/webpack.js --watch --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
  "hot": "NODE_ENV=development webpack-dev-server --inline --hot --config=node_modules/laravel-mix/setup/webpack.config.js",
  "production": "NODE_ENV=production node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"
},

This adds NPM scripts which you’ll need to use to compile the Sass. You’ll need to run these commands from within the sub-theme.

The two important scripts are:

$ npm run watch

Use this script to automatically compile when a file is changed. This should be used locally while developing a site.

$ npm run production

Conclusion

I hope now you have a better understanding on how to use Bootstrap in your next Drupal project