A Step-by-Step Guide to Help You Build Your First Drupal Custom Theme.
Development on Drupal can be a bit frustrating if you are new to the platform. But learning Drupal custom theme development is worth the time you invest in it. First, you need to understand what Drupal is and what it does.
What is Drupal?
Drupal is an open-source Digital Experience Platform (DXP) with a track record of innovation in customer experience. A DXP is a set of integrated technologies that help optimize customer journeys across multiple channels.
Difference between DXP and content management system (CMS)
DXP is broader than the traditional content management systems as it can sync, manage and push content across many channels. These include web, billboards, IoT, kiosks and more.
This guide teaches you the basics of Drupal custom theme development. If you want to learn in-depth about Drupal custom theme development, visit the Drupal website.
Step-by-step guide to Drupal custom theme development:
Name Your Theme
First, you need to create a name for the theme. Make sure the theme’s machine name starts with a letter, uses lower-case, contains Latin letters or numbers and avoids spaces by using underscores. Try to keep the name within 50 characters. As an example, we will name our theme “custom theme”.
Create the Theme Folder
After naming the theme, create a folder for the theme with the same name. This folder will contain all the necessary information about your Drupal custom theme development project. For this, create a folder under the ‘web/themes/custom’ folder. For example, “custom_theme”.
Create info.yml File
Next, you need to create an info.yml file. This is the main file of your theme’s folder and it is required for Drupal custom theme development. Similar name rules will apply to this file. So your info.yml file will be “custom_themes”.
The info.yml file defines parameters or key-value pairs for your theme. Some parameters are required for Drupal custom theme development, while some are optional. Once you have defined the required parameters, you will be able to see your theme on the Appearance Page.
Main parameters to define in the info.yml file:
- Name (required): The human-readable name of your theme ,i.e. custom theme.
- Type (required): The type of extension. In this case, it is “theme”.
- Core_version_requirement (required): Specifies the Drupal version your theme is compatible with. Example, core_version_requirement: ^8 // ^9. This can also be narrowed down to specific Drupal versions.
- Base theme (required in Drupal 9): This option helps choose between Drupal custom theme development from scratch or inheriting resources of an existing theme.
Set the “base theme” value to “false” for a new custom theme. To create a subtheme that inherits resources from a parent theme, specify the parent theme — for example, base theme: classy.
Create the libraries.yml File
Now, you will need to create a libraries.yml file at the theme’s root directory. This file specifies all the libraries we need for Drupal custom theme development. For example, name it custom_theme.libraries.yml
Link the CSS and js Directories to libraries.yml
You will also need to create CSS and js directories. These directories should have corresponding files — styles.css and script.js. After creating these directories and folders, link them to the libraries.yml file.
The global-styling library helps load your styles on all the pages. List the global-styling library in the libraries.yml file.
Link libraries.yml to Your Theme
After creating the libraries.yml file, you need to link it to your theme. To do that, add it to the info.yml file. This will apply to the whole theme.
Define Regions
To fully utilize Drupal custom theme development options, you can define regions in the info.yml file. Once you define at least one region, the default ones will be disabled.
Define regions under the ‘regions’ key. To define your Drupal custom theme development regions, list them below the regions key.
As you can see in the image below, “header” is the region’s id. It should be in lower case and should not contain spaces. “Header” is the name of the region and can use uppercase and spaces.
Override the twig File
To ensure your Drupal custom theme development goes smoothly, overriding page.html.twig is necessary. This is done so that our regions are used instead of classy theme’s.
- Go to the file, core/modules/system/templates/page.html.twig
- List all regions as Twig variables. For example, header will become {{page.header}}
Install Your Custom Theme
To activate the theme you have created with Drupal custom theme development, go to Appearance. Your custom theme will be in the uninstalled themes section.
Click on the Install and set as default option to apply your Drupal theme to your site. After installing it, go to Block Layout under Structure. Your custom Drupal theme will appear here.
Click on the link “Demonstrate block regions (custom theme)” and you will be able to see all of your regions.
Use CSS for Design
You are almost done with Drupal custom theme development. Final touches in design using CSS or SCSS help make your site more aesthetic.
Inspect your required region and add CSS to that region’s class.
Tip: To add hooks or suggestions for the twig file, add the .theme file in your custom Drupal theme. These help with targeted overrides in your theme for templates.
Hopefully, this guide will help you start your first Drupal custom theme development project.
