Drupal developers and interface engineers do not always create custom themes from scratch. Sometimes, we are asked to create starter themes that we begin any project from or subthemes that extend the functionality of a base theme. Having the knowledge of how to handle each of these situations is important. In this article by Chaz Chumley, the author of Drupal 8 Theming with Twig, we will be discussing some starter themes and how to work around the various libraries available to us.

(For more resources related to this topic, see here.)

Starter themes

Any time we begin developing in Drupal, it is preferable to have a collection of commonly used functions and libraries that we can reuse. Being able to have a consistent starting point when creating multiple themes means we don’t have to rethink much from design to design. The concept of a starter theme makes this possible, and we will walk through the steps involved in creating one.

Before we begin, take a moment to use the drupal8.sql file that we already have with us to restore our current Drupal instance. This file will add the additional content and configuration required while creating a starter theme. Once the restore is complete, our home page should look like the following screenshot:

This is a pretty bland-looking home page with no real styling or layout. So, one thing to keep in mind when first creating a starter theme is how we want our content to look. Do we want our starter theme to include another CSS framework, or do we want to create our own from scratch?

Since this is our first starter theme, we should not be worried about reinventing the wheel but instead leverage an existing CSS framework, such as Twitter Bootstrap.

Creating a Bootstrap starter

Having an example or mockup that we can refer to while creating a starter theme is always helpful. So, to get the most out of our Twitter Bootstrap starter, let’s go over to http://getbootstrap.com/examples/jumbotron/, where we will see an example of a home page layout:

If we take a look at the mockup, we can see that the layout consists of two rows of content, with the first row containing a large callout known as a Jumbotron. The second row contains three featured blocks of content. The remaining typography and components take advantage of the Twitter Bootstrap CSS framework to display content.

One advantage of integrating the Twitter Bootstrap framework into our starter theme is that our markup will be responsive in nature. This means that as the browser window is resized, the content will scale down accordingly. At smaller resolutions, the three columns will stack on top of one another, enabling the user to view the content more easily on smaller devices.

We will be recreating this home page for our starter theme, so let’s take a moment and familiarize ourselves with some basic Bootstrap layout terminology before creating our theme.

Understanding grids and columns

Bootstrap uses a 12-column grid system to structure content using rows and columns. The page layout begins with a parent container that wraps all child elements and allows you to maintain a specific page width. Each row and column then has CSS classes identifying how the content should appear. So, for example, if we want to have a row with two equal-width columns, we would build our page using the following markup:

<div class="container">

    <div class="row">

        <div class="col-md-6"></div>

        <div class="col-md-6"></div>

    </div>

</div>

The two columns within a row must combine to a value of 12, since Bootstrap uses a 12-column grid system. Using this simple math, we can have variously sized columns and multiple columns, as long as their total is 12. We should also take notice of these following column classes, as we have great flexibility in targeting different breakpoints:

• Extra small (col-xs-x)
• Small (col-sm-x)
• Medium (col-md-x)
• Large (col-lg-x)

Each breakpoint references the various devices, from smartphones all the way up to television-size monitors. We can use multiple classes like  class=”col-sm-6 col-md-4″ to manipulate our layout, which gives us a two-column row on small devices and a three-column row on medium devices when certain breakpoints are reached.

To get a more detailed understanding of the remaining Twitter Bootstrap documentation, you can go to http://getbootstrap.com/getting-started/ any time. For now, it’s time we begin creating our starter theme.

Setting up a theme folder

The initial step in our process of creating a starter theme is fairly simple: we need to open up Finder or Windows Explorer, navigate to the themes folder, and create a folder for our theme. We will name our theme tweet, as shown in the following screenshot:

Adding a screenshot

Every theme deserves a screenshot, and in Drupal 8, all we need to do is have a file named screenshot.png, and the Appearance screen will use it to display an image above our theme.

Configuring our theme

Next, we will need to create our theme configuration file, which will allow our theme to be discoverable. We will only worry about general configuration information to start with and then add library and region information in the next couple of steps.

Begin by creating a new file called tweet.info.yml in your themes/tweet folder, and add the following metadata to your file:

name: Tweet

type: theme

description: 'A Twitter Bootstrap starter theme'

core: 8.x

base theme: false

Notice that we are setting the base theme configuration to false. Setting this value to false lets Drupal know that our theme will not rely on any other theme files. This allows us to have full control of our theme’s assets and Twig templates.

We will save our changes at this juncture and clear the Drupal cache. Now we can take a look to see whether our theme is available to install.

Installing our theme

Navigate to /admin/appearance in your browser and you should see your new theme located in the Uninstalled themes section. Go ahead and install the theme by clicking on the Install and set as default link.

If we navigate to the home page, we should see an unstyled home page:

This clean palate is perfect while creating a starter theme, as it allows us to begin theming without worrying about overriding any existing markup that a base theme might include.

Working with libraries

While Drupal 8 ships with some improvements to its default CSS and JavaScript libraries, we will generally find ourselves wanting to add additional third-party libraries that can enhance the function and feel of our website. In our case, we have decided to add Twitter Bootstrap (http://getbootstrap.com), which provides us with a responsive CSS framework and JavaScript library that utilize a component-based approach to theming.

The process actually involves three steps. The first is downloading or installing the assets that make up the framework or library. The second is creating a *.libraries.yml file and adding library entries that point to our assets. Finally, we will need to add a libraries reference to our *.info.yml file.

Adding assets

We can easily add Twitter Bootstrap framework assets by following these steps:

1. Navigate to http://getbootstrap.com/getting-started/#download
2. Click on the Download Bootstrap button
3. Extract the zip file
4. Copy the contents of the bootstrap folder to our themes/tweet folder
5. Once we are done, our themes/tweet folder content should look like the following screenshot:
   

Now that we have the Twitter Bootstrap assets added to our theme, we need to create a *.libraries.yml file that we can use to reference our assets.

Creating a library reference

Any time we want to add CSS or JS files to our theme, we will either need to create or modify an existing *.libraries.yml file that allows us to organize our assets. Each library entry can include one to multiple pointers to the file and location within our theme structure. Remember that the filename of our *.libraries.yml file should follow the same naming convention as our theme.

We can begin by following these steps:

1. Create a new file called tweet.libraries.yml.
2. Add a library entry called bootstrap.
3. Add a version that reflects the current version of Bootstrap that we are using.
4. Add the CSS entry for bootstrap.min.css and bootstrap-theme.min.css.
5. Add the JS entry for bootstrap.min.js.
6. Add a dependency to jQuery located in Drupal’s core:

   bootstrap:
   
     version: 3.3.6
   
     css:
   
       theme:
   
         css/bootstrap.min.css: {}
   
         css/bootstrap-theme.min.css: {}
   
       js:
   
         js/bootstrap.min.js
   
       dependencies:
   
         - core/jquery

7. Save tweet.libraries.yml.

In the preceding library entry, we have added both CSS and JS files as well as introduced dependencies.

Dependencies allow any JS file that relies on a specific JS library to make sure that the file can include the library as a dependency, which makes sure that the library is loaded before our JS file. In the case of Twitter Bootstrap, it relies on jQuery, and since Drupal 8 has it as part of its core.libraries.yml file, we can reference it by pointing to that library and its entry.

Including our library

Just because we added a library to our theme doesn’t mean it will automatically be added to our website. In order for us to add Bootstrap to our theme, we need to include it in our tweet.info.yml configuration file.

We can add Bootstrap by following these steps:

1. Open tweet.info.yml
2. Add a libraries reference to bootstrap to the bottom of our configuration:

   libraries:
     - tweet/bootstrap

3. Save tweet.info.yml.

Make sure to clear Drupal’s cache to allow our changes to be added to the theme registry. Finally, navigate to our home page and refresh the browser so that we can preview our changes:

If we inspect the HTML using Chrome’s developer tools, we should see that the Twitter Bootstrap library has been included along with the rest of our files. Both the CSS and JS files are being loaded into the proper flow of our document.

Summary

Whether a starter theme or subthemes, they are all just different variations of the same techniques. The level of effort required to create each type of theme may vary, but as we saw, there was a lot of repetition. We began with a discussion around starter themes and learned what steps were involved in working with libraries.

Resources for Article:

---

Further resources on this subject:

• Using JavaScript with HTML [article]
• Custom JavaScript and CSS and tokens [article]
• Concurrency Principles [article]

---