How to Create a Simple Responsive Drupal 8 Theme From Scratch

One of the first jobs that any Drupal developers need to do is to understand how Drupal works and become used to it. And creating a Drupal theme from scratch is a skill that they are in absolute need of. But drupal theming can be hard, and overwhelming, especially for new users who hold no experience in the subject. But don’t worry. Get the shadow off your mind as we are going to walk you through a detailed process to create your own basic and responsive drupal 8 theme.

Why create a D8 theme from scratch?

• Understand how drupal theming works - why there is such a step, why you need to have these files.
• Have your own base theme, rather than relying on the products of someone else.
• Improve Drupal theming skill. The most useful way to study is to practice and create one for yourself from the ground up.
• Learn the differences between Drupal 8 & Drupal 7 theming.

Assumptions

• Read our post about basic Drupal 8 theming (If you don't, no problems. You still can create one).
• Basic knowledge about styling (html, css).
• Basic knowledge about responsive design (we use Bootstrap for responsiveness) (Skip this, if you don't want to use Bootstrap)

Understanding Theme Folder Structure & Theme Files

Before starting, we need to know how a complete D8 theme structure looks like. This is to help you have a visual image in your head to get your job easier in the the subsequent steps.

|-config |    |-install |    |    |-themename.settings.yml |    |-schema |    |    |-themename.schema.yml |-css |    |-style.css |-js |    |-business.js |-images |    |-buttons.png |-includes |    |-bootstrap |    |-flexlider |-templates |    |-block.html.twig |    |-comment.html.twig |    |-html.html.twig |    |-maintenance-page.html.twig |    |-node.html.twig |    |-page.html.twig |-favicon.ico |-logo.png |-screenshot.png |-themename.breakpoints.yml |-themename.info.yml |-themename.libraries.yml |-themename.theme

And below are the descriptions of the most common theme files & keys you can find in a D8 theme.

• .info.yml this mandatory file gives information about your theme
• .libraries.yml defines your libraries (mostly your JS, CSS files).
• .breakpoints.yml defines the points to fit different screen devices.
• .theme The PHP file that stores conditional logic and data preprocessing of the variables before they are merged with markup inside the .html.twig file.
• /css where your css files lay. Must be defined in the info, and libraries file to operate.
• /js where your js files lay. Must be defined in the info, and libraries file to operate.
• /images where you theme images are stored. It is a good practice to put images in this folder.
• /includes where 3rd-parties libraries (like Bootstrap, Foundation, Font Awesome,etc) are put. It is a good practice to store them in this folder
• /templates where all your template files (ones that provide html markup of your theme page) are placed.
• logo.png your theme logo if you're using one.
• favicon.ico your theme favicon if you're using one.
• screenshot.png your theme screenshot that will be displayed in the admin/appereance.

Your Theme Layout Display

We should decide how the website layout looks like first. We are going to make it really simple. As shown below, your Drupal template will consist a header, sidebar, content area, and footer.

After you have grasped some basic ideas about your template folder, its files, and the layout of your theme, let's move to the main part - create a simple responsive Drupal 8 template.

Step by Step to Create Your Drupal Theme

1. Create theme folders

The foremost thing you must know is that in Drupal 8, the theme folder lies in core/theme, not sites/all/theme like in Drupal 7 anymore. The basic theme folder will have sub-folders for images, CSS, JS, templates (this one holds twig templating files), and includes (to store 3rd-party libraries ). We will create a basic theme folder structure as follows:

2. Create the .info.yml file

How do Drupal templating engine scan for the information of your theme? The .info.yml file is the answer. It is no denying that the .info.yml file is the most important file you need to include first. Note that if you have been acquainted with Drupal 7 theming system, [theme_name].info is no longer applied. In D8, you must use .info.yml extension for the info file.

A compplete info.yml file will have these following keys:

1. name (required) The name of your theme, which will show up in the administration/appearance D8 admin
2. description(optional yet recommended) What you want to describe about your theme, which also appear in the Administration/Appearance
3. version (optional) The version of your theme. It will show behind the theme name.
4. type (required) Notify Drupal about the type of extension. E.g. Theme, Module, or Profile.
5. core (required) The major version of Drupal core that is supported
6. base theme (optional yet recommended) Indicate what base theme your custom theme will inherit. If not defined, Drupal will use “Stable” as your base theme.
7. region (optional) Define the regions of the theme where you place your blocks. If not declaring any regions in the .info.yml file, Drupal will use the default regions of the core. Keep in mind that if you define the regions even just one, default regions are no longer applied. “content” region is required to exist if you define regions in the info file

Now for your .info.yml file, we'll include these values

headline, header, content, sidebar, footer have been included in the region section. This is to notify Drupal templating machine that your theme will have these regions. However, defining them here is not enough. These regions still do not show up. You must also include them in the page.html.twig file. (which we will cover in step 4). Notice that classy is used as the base theme. In D8, there are 2 default base themes - Stable & Classy. We have explained the differences of the two in our past post. Basically,

We like to use Classy as it has given some predefined proper classes that make the styling job more convenient.

3. Define your libraries file

This is a change in D8. While in D7, you will indicate all your libraries (like styling - css & scripts - js) in the .info file, now you have to define them in a separate file - the .libraries.yml file. In the case of your theme, we will use style.css for styling, and the Bootstrap library for responsive display. So we will place the style.css file in the core/css folder. The bootstrap libraries (bootstrap.css) will lie in the includes/bootstrap/css directory.

4. Create theme regions

4.1 Understanding drupal template files

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 theme
  html.html.twig - defines every page on the site
    page.html.twig - defines every page on the site
       node.html.twig - defines every node on the site
        region.html.twig - defines every region on the site
          block.html.twig - defines every block on the site
            field.html.twig - defines every dynamic element on the site

If you want to change the way your default HTML, and pages look, you can create your own version of the files above. The most important file that you want to alter now is the page.html.twig. Is is the so-called HTML skeleton of your page as it will render how your page HTML layout will look like. Drupal will read this file and tell how your homepage displays, and even how all of your pages appear if you don't include other template files. So the job now is to make your own a page.html.twig file.

4.2 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)

Note: 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.

We'll create basic html regions for the page, including headline, header, main, and footer regions. Notice that if you add these regions, you must define them in your info.yml file first.

<div id="page">
    <section id="headline">
    </section> 
    <header>
    </header>
    <section id="main">
    </section>
    <footer>
    </footer>
</div><

Next, put all of the regions of your page into a Bootstrap container for ease of responsiveness. We'll add these codes between each section (headline, header, main, footer).

<div class="container">...
</div>

For the content and the sidebar region, we'll use the column class of Bootstrap so that these two regions will be divided as follows: Main content will constitute 75% of the site width, sidebar will account for 25%. That is for the desktop. For mobile screens, main content and sidebar will be displayed full width (100%). Your main section codes will look like this

  <section id="main">
    <div class="container">
      <div class="row">
          <div id="content" class="col-md-9 col-sm-9 col-xs-12">
              {{ page.content }}
          </div>
              {% if page.sidebar %}
          <aside id="sidebar" class="sidebar col-md-3 col-sm-3 col-xs-12">
               {{ page.sidebar}}
          </aside>
               {% endif %}
      </div>
    </div>
  </section>

The last step of your page.html.twig file is to add these twig codes to the headline section to render them to the page. (If you don’t know twig syntax, return to our past post, or read twig syntax documentation).

The above codes create a conditional to check if the headline region has something in it. If there is, the headline region will be printed out. This is a good practice to ensure that empty markup will not be printed to the page. Now add the similar and relevant codes to the header, content, sidebar, and footer. The content section is an exception. It does not need a conditional statement because there will always be something in the content region. After all done, the complete codes of your page.html.twig file will be be like this:

<div id="page">
  {% if page.headline %}
    <section id="headline">
    <div class= "container">
      {{ page.headline }}
    </div>
    </section> 
    {% endif %}
  <header id="header">
    <div class="container">
        {{ page.header }}
    </div>
  </header>
  <section id="main">
    <div class="container">
        <div class="row">
            <div id="content" class="col-md-9 col-sm-9 col-xs-12">
                {{ page.content }}
            </div>
                {% if page.sidebar %}
            <aside id="sidebar" class="sidebar col-md-3 col-sm-3 col-xs-12">
                 {{ page.sidebar}}
            </aside>
                 {% endif %}
        </div>
    </div>
    </section>
  {% if page.footer %}
    <footer id="footer">
      <div class="container">
        {{ page.footer }}
      </div>
    </footer>
  {% endif %}
</div>

5. Create theme content

Now that you have given enough definitions for your theme, let’s start enabling the theme, and create content.

5.1 Enable the theme

Your theme won’t work until you activate it. Go to /admin/appearance, find your basis theme, and choose set as default.

5.2 Place content on respective regions

Each section on Drupal will be called block. To make it appear in the right place, you need to place it in the right regions. Since we have created regions, navigate to basis/admin/structure/block, and you will see many sections, encompassing headline, header, content, sidebar, footer. For your basis theme, we would like it to have a website design layout as seen.

To do that, place these blocks on the relevant regions in the basis/admin/structure/block

Header
    Main navigation (your menu)
    Site Branding (Your logo, and slogan)

Content (your front-page display)

Sidebar 
    Search Form

Footer
    Powered by Drupal

5.3. Create logo

By default, Drupal will look for the logo.svg in the theme\logo.svg for logo display. So you need to create one to enable it. You will also have the options to choose what to display - site logo, site name, or site slogan in /admin/structure/block/manage/sitebranding

5.4 Create theme screenshot

Your screenshot will show up next to your theme in the admin interface admin/appearance. To create one, place an image file named screenshot.png in your theme directory.

6. Styling your theme

Now take your web design, Front-end skills, and your creativeness to create the appearance of the theme that you like. For our D8 themes, we use Bootstrap for responsiveness, and SASS for ease of styling. But it’s our working method. Just do what you want.

7. Enjoy the result

Finally, you have a responsive Drupal theme with the menu and main content on the left, sidebar on the right with search form block. And design it like you want with your Front-end improvisational skills.

DOWNLOAD THEME

You are able to use our theme that we have guided you in this post for reference. Note that, we have made our very basic styling in the style.css file to make the page less rough. So if you want to style your own theme, simply change the css file to your liking.

Questions: If you have any questions related to your steps creating the Drupal 8 theme, or any issues about Drupal 8 theming, please post a comment below.