Setting a New Theme and Build Process

In this chapter, we will see the options we have for styling a Drupal website, starting from the themes that are available with the CMS itself, up to why we might choose to implement a custom solution.

You will learn how to use the new starterkit approach of Drupal 10 to set up and maintain a custom theme. Then we’ll see how to use modern frontend workflows, including webpack to build the assets, Tailwind CSS to manage the styles, and BackstopJS to avoid visual regressions.

Finally, you will learn how to set up a GitHub action that runs the checks for you every time you push some code via a fully functional Continuous Integration (CI) pipeline.

By the end of the chapter, we will have a solid and automatic build process that will build our styles, ensure the quality of the code we’ll write, and avoid functional and visual bugs.

We will cover the following topics:

• Where to start
• Using a starterkit
• Which tools...

Where to start

Drupal is a CMS, and its primary feature is to allow non-technical users to insert, edit, and manage complex editorial content using a web interface (the administration interface). Content can then be shown to end users in multiple ways. Starting from Drupal 8, the system is API-frst, and can be used as the backend in a headless architecture. But, out of the box, Drupal renders its content as HTML pages (we’ll refer to this as the frontend throughout the rest of the book).

This double behavior is possible thanks to the high level of decoupling between where the content is built in Drupal core and where it is converted into HTML for the final output. The layer that converts content into HTML is called the theme layer.

Drupal allows users to choose different themes for both the administration and frontend interfaces.

Themes are hierarchical, where a child theme can extend or alter its parent theme, adding new CSS, replacing HTML templates, or changing the...

Using a starterkit

Until Drupal 9, the recommended way to create a new custom theme was to extend from a core theme called Classy. The Classy theme contained a copy of all the templates from Drupal core with markup enriched by some useful classes. So, nearly every custom theme out in the wild is a sub-theme of Classy. This has caused some issues with the evolution of Drupal, because Classy needed to stay backward compatible with its first version (which came out with Drupal 8).

Classy has been deprecated and removed from Drupal 10 as a new way of creating custom themes has emerged.

Drupal 10 has a new theme generator command that can be used to create a custom theme from a starterkit. Instead of sub-theming Classy, you can use this command to generate your new theme as a copy of some starterkit. Basically, instead of extending a base theme, you rather copy all the assets of that theme to a new one, completely owned by you. Core provides a default starterkit with markup similar...

Which tools to use

Gone are the days when the frontend was a mix of HTML and CSS files tied together with some manual work. Today there are a lot of tools that process, transform, and transpile our source files to generate the most up-to-date and browser-compatible CSS output. Some of the tools we’ll use in our custom theme development are the same used by Drupal for its own core themes.

Tailwind CSS

This is not a book about CSS, so we don’t want to spend time crafting style files, deciding how to name things and how to structure classes. Of course, you can still do that. You can write all the CSS or SCSS files that you need from scratch, or by using a framework such as Bootstrap or Foundation, following methodologies such as SMACSS (http://smacss.com) and BEM (https://getbem.com).

Instead, we’ll use Tailwind CSS (https://tailwindcss.com/).

Tailwind CSS uses a utility-first approach: instead of providing a set of classes for elements such as buttons...

Ensuring coding standards

We will write a lot of code to implement the requested layout and we will use different languages (Twig, HTML, CSS, and JavaScript). To avoid every developer using their own style, we must define a set of rules that everyone in the team has to adhere to. This will greatly simplify the task of reading the code for other developers, and also help when reviewing code changes.

Drupal defines a set of tools and rules for its own files, and we should use the same standards too.

We’ll use different tools for different languages:

• Stylelint for CSS files
• ESLint for JavaScript files
• PHPCS for PHP files

Stylelint

To add Stylelint (https://stylelint.io/) to our theme, follow these steps:

1. Open a shell into the web container:

   ddev ssh

2. Then go to the theme folder:

   cd web/themes/custom/alps_trips

3. Install the required packages:

   yarn add –D stylelint stylelint-config-standard stylelint-config-tailwindcss stylelint-order...

Setting up a build process

Every time some new code is pushed to a remote repository, we must run a set of checks to ensure the quality of the code we’re providing. Here and in the following chapters, we set up checks for coding standards and tests for visual regression and JavaScript. Of course, you can (and should) test more (using tools such as Behat (https://docs.behat.org), for example).

As we’re using GitHub as our code repository, we define a GitHub action (https://github.com/features/actions) to run all our checks. GitHub Actions is free for public repositories and is limited to 2,000 minutes of execution every month for private projects.

GitHub Actions basically runs a set of commands on our code base in a Docker container, quite similar to what we’ve done until now on our local environment. To simplify the setup even further, we’re also going to use DDEV in the GitHub Actions pipeline.

GitHub actions are defined as YAML files in the .github...

Summary

In this chapter, we discovered the advantages and disadvantages of the different solutions we can choose from when we need a Drupal theme. We saw when it’s better to use a contrib theme and when to develop a custom one.

We then learned which tools can simplify our work by automating all the repetitive tasks, ensuring code quality and avoiding bugs.

Finally, we also saw how to delegate all the automatic checks to a CI pipeline by defining a GitHub action.

In Chapter 3, How Drupal Renders an HTML Page, we will deep dive into the theming layer of Drupal to understand the complete flow that starts with content and ends with rendered pages.