Which software to use to run a project locally can be a matter of taste or a best practice enforced by a team (or an organization). In this section, we’re going to install a selection of software that is free (at least for personal use) and, if possible, open source.

The following selection is not mandatory but it will simplify reading the rest of the book because all the screenshots and examples are based on the platforms mentioned.

Git

Git is a distributed version control system that helps developers manage their source code changes over time. It tracks changes in code and allows multiple developers to collaborate on a project simultaneously. Git allows developers to work on their own copy of the code, experiment with different changes, and merge those changes back into the main code base when they're ready. It also allows for backup and recovery of code in case of system crashes or data loss. Git is widely used in software development and other collaborative projects.

The code used in this book is hosted in a Git repository provided by a company called GitHub. From that remote repository, you can obtain (clone) a copy of the code. A Git client is available by default on Linux and macOS systems; on Windows, you must use the WSL 2 subsystem.

You usually interact with Git using the command line, but different tools exist to provide a graphical user interface (one of these is Visual Studio Code, which we’ll install later).

Docker

Docker is a technology used to replicate the same software stack everywhere, independently of the host operating system. This is mandatory to keep consistency between all the developers in a team who may individually use different operating systems. Docker is also useful for replicating as much as possible the configuration of the production environment or having multiple stacks on the same local machine, each one with different software versions and configurations. Maybe you’re working on an old Drupal 7 website that requires PHP 7.*, and a shiny new Drupal 10 website that requires PHP 8.1.

Docker can be installed in different ways, but here we’ll use the simplest one: Docker Desktop.

Docker Desktop is a commercial application developed by the Docker team itself and it’s free for use unless you’re in a large enterprise (more than 250 employees or more than 10 million USD in annual revenue) or some government entity.

Detailed instructions on how to install it can be found at https://docs.docker.com/get-docker/. In the next examples, we’ll use macOS, but the setup and usage are the same on Windows and Linux.

After the installation, you may need to set up Docker Desktop to match your system. Here’s how to do that:

1. To run Docker, simply click on its icon in the applications list. Once it's up and running, you'll see the Docker icon appear on the top right of your screen. Clicking on the icon will open a menu where you can easily check if Docker Desktop is running smoothly or if there are any issues to address.

Figure 1.1 – Docker Desktop menu

2. Click on the Preferences link to open the Preferences window.
3. Click on the Resources | Advanced section to tweak how many of your system resources Docker can consume. On the right pane, you can select how many CPUs and how much memory, swap, and disk size Docker can use:

Figure 1.2 – The Advanced section of Docker Desktop

In this case, I’ve set my system to grant Docker up to 4 CPUs and 12 GB of memory. Usually, you’ll want to choose half of the resources of your system.

4. Click on the Resource | File sharing section to configure which directories can be bind-mounted into Docker containers:

Figure 1.3 – The File sharing section of Docker Desktop

In a production environment, you will have a Docker image that contains both the PHP interpreter and the code of the website, but in a local environment, to speed things up, the code stays on the host (your local machine) and is then mounted (made accessible) to the Docker container using a volume. Docker Desktop allows only for a subset of your computer filesystem to be mounted to a Docker container (for security and performance); you can set which directory to include in the File sharing section of the Preferences pane. The /Users directory is included by default, so you can just clone the demo repository somewhere inside this folder.

To be sure everything is clear, here you can find a list of base Docker concepts as a reference:

• Docker engine: The core system that allows you to build and run containers.
• Image: Contains a list of instructions used to build a container.
• Container: This is the executable image that contains everything needed to run an application.
• Volume: This is the system used by Docker to persist a container’s data between executions. So, container data stored in a volume will be preserved even if the container itself is stopped or removed. Furthermore, the same volume can be attached to multiple containers.
• Compose: This is a tool that allows a set of containers to work together in the same network.

To run a Drupal website, we need at least two containers—one with a web server and one with a database server. Other containers can be useful during development, such as one to explore the database data and one to catch sent emails (for debugging purposes).

Of course, you can set up your stack from scratch, choose which images to use (or build some custom ones), configure them, find a way to orchestrate them, and so on. Because this is a book on Drupal and not Docker, we’ll use a tool that does everything we need for free.

DDEV

DDEV is an open source tool to speed up local PHP development. It uses Docker to configure and run everything that is required to work on a Drupal (or other PHP-based) website. It also provides a lot of commands to interact with the stack.

DDEV configurations can be added to Git and shared with all developers in the team. In this way, whoever clones and spins up the project will have exactly the same environment.

Again, the installation procedure depends on your computer's operating system. You can find all the details on the project website: https://ddev.readthedocs.io.

Note

Pay attention to the installation procedure—one required step is about installing and configuring mkcert (https://github.com/FiloSottile/mkcert). mkcert allows you to visit any DDEV-managed website using HTTPS just as it will be in production.

DDEV doesn’t have a graphical interface; everything is managed through the command line. To see a list of all available DDEV commands, you can simply type ddev on your terminal:

ddev

The demo code you’ll download in the next section contains a ready-to-use DDEV setup, located in the .ddev folder in the root of the repository.

Visual Studio Code

More than just a code editor, we need a full IDE to support our work with different kinds of files. Here, we have a lot of choices, which are mainly driven by personal taste and budget. One IDE that is free but very powerful is Visual Studio Code.

Visual Studio Code is a free application that runs nearly everywhere, from every operating system through the web (it’s the IDE that powers https://github.dev and https://www.gitpod.io, for example).

Note

You can find detailed instructions about how to download and install Visual Studio Code at https://code.visualstudio.com/docs.

Visual Studio Code's features can be enriched by installing extensions; we’ll need some of them to speed up our work, including the following:

• PHP Intelephense
• PHP Debug
• Tailwind CSS IntelliSense
• Twig Language 2
• Prettier (a code formatter)

To install an extension, follow these steps:

1. Open Visual Studio Code.
2. Click on the View | Extensions menu item to open the extensions view.
3. Use the search engine to find the extension to add.
4. Click on the Install button under the extension name in the right pane:

Figure 1.4 – PHP Intelephense is one of the most complete plugins for working on PHP with Visual Studio Code

Our local stack is ready to be used. In the next section, we’ll use it to set up and run the demo website.

Now that the local environment is ready, we can clone the repository of the demo site.

Cloning and building

The repository has two branches, one with the final website (the same one that you will have at the end of this book) and one with just the CMS configured. We’ll start with the latter, but if you want to see the final result you can switch to the first one.

Start by cloning the repository in a local folder. Remember that Docker Desktop limits the folder that can be mounted in a container, so choose one that is included (usually a subfolder of your home directory is the safer choice):

git clone https://github.com/PacktPublishing/Modernizing-Drupal-10-Theme-Development

Then, cd to that folder and start the DDEV stack:

ddev start

This command starts the stack but doesn’t build the website; to do that, you must run this command:

ddev build

build is a custom command, not part of the original DDEV installation, and it’s available because it has been defined in the .ddev/commands/web folder of the repository you’ve cloned. In the .ddev/commands folder, you will find some other custom commands that we have added to DDEV, and you can add your own too. Commands are bash scripts that run on your host shell or in one of the running containers, depending on which folder contains it:

• .ddev/commands/host: The host computer
• .ddev/commands/web: The web container (where the web server and the PHP interpreter run)
• .ddev/commands/db: The container that runs MySQL

Note

The folder that contains the website is mounted into the web container. The files are exactly the same, but they can be accessed from your local computer and from the web container. Bear in mind that the absolute path may be different between the two systems. On your local computer, it will be something such as /Users/lussoluca/Sites/modern_drupal_themes, but on the web container, it will always be /var/www/html. You can connect to a shell that runs in the web container using the ddev ssh command. To close the web container shell and return to the host shell, just type exit and hit Return.

Internally, the build command uses a set of tools to download all the required dependencies and install the website.

Every time you want to reinstall the demo website from scratch, you can execute the build command again.

DDEV provides some other useful commands, as follows:

• stop: Stop and remove the containers of a project. Does not lose or harm anything.
• describe: Get a detailed description of a running DDEV project.
• delete: Remove all project information (including the database) for an existing project.

And there are many more—just type ddev and hit Enter to see them all.

Note

During the start process, DDEV may print a message such as “ssh-agent container is running: If you want to add authentication to the ssh-agent container, run 'ddev auth ssh' to enable your keys.” You can safely ignore this warning in our context.

Composer

All the external PHP dependencies needed to run the website (such as contrib modules and development tools) are not versioned in the Git repository. Instead, they’re downloaded from the internet using a tool called Composer. Composer manages packages using a Semantic Versioning approach, where every package has a version in the form of major.minor.patch (more information at https://semver.org). The application and its dependencies are described in a file called composer.json, usually located in the root folder of the project. Composer has a lot of commands, but the three most used are shown next.

Here’s the first one:

composer update –prefer-dist

This updates all the packages to the latest version (always respecting the Semantic Versioning rules). This command also updates (or creates) a composer.lock file that stores the exact version that has been installed for each package. The composer.lock file must be added to the Git repository and is mandatory to allow every developer on the team, the CI/CD pipelines, and remote environments to have the same version of every dependency.

The second most used Composer command is this one:

composer install –prefer-dist

This reads from a composer.lock file and downloads the exact version of every package.

Finally, when you need a new package (for example, the WebProfiler contributed module) you can run the following command:

composer require drupal/webprofiler

The ddev build command already executes composer install for you, and you can see the list of required packages in the composer.json file in the root folder of the project.

Configuration management

Starting from Drupal 8, the system exports all the configuration needed to recreate the site into a folder, where each configuration is stored as a YAML file. A complex website can have hundreds of such files. Drupal doesn’t use those files directly; they must be imported into the database (this means that if you change one of those files manually, it needs to be imported again to be seen by Drupal). A way to package configurations is to create an installation profile. Drupal core has some ready-to-use installation profiles, such as Standard, Minimal, and Umami (you can see the full list by installing Drupal using the web interface or by looking in the core/profiles folder). In our demo website, we have defined a new installation profile, called AlpsTrips, in the web/profiles folder.

Just about everything in Drupal has a double name—one for humans (such as the profile name, AlpsTrips) and one for machines (that has more restrictive rules, such as no spaces, only some special characters allowed, and so on). The machine name for the AlpsTrips profile is alps_trips_profile.

Drush

One of the packages downloaded by Composer is Drush (https://www.drush.org/latest/). Drush is not a Drupal module and it isn’t used by the website itself; it’s used to automate operations on a Drupal website from the command line. Tasks such as installing Drupal, managing content or users, installing modules, and so on can all be done without even opening a browser instance. To see all the available Drush commands, you can run the following:

ddev drush

DDEV will forward the call to the Drush instance present in the web container.

Default Content

The content of a Drupal website stored in the same database that is used for configurations, but unlike configurations, the core of Drupal doesn’t have any tools for exporting them. To style the website, we need some content to work on (but also for showing the work in progress to the customer, or for writing end-to-end tests). This can be done in a lot of different ways; the community has not yet agreed on the tool to be used by default.

One solution is to use the Default Content contributed module (https://www.drupal.org/project/default_content).

On the demo website repository, we've used Default Content to export a set of dummy contents to a custom module (located on the web/modules/custom/demo folder). When this module is enabled, the contents are automatically imported into Drupal.

Yarn

The latest tool that is used to build our website is Yarn. Yarn is a package manager for Node.js, and we need it for the same reason we need Composer for PHP packages: we don’t want to save the dependencies in our repository. Similar to Composer, Yarn uses two files—package.json and yarn.lock—to describe which packages to download and at which exact version. Yarn can also be used to define and run custom scripts, such as building CSS and JavaScript assets.

All of those tools are used by our build command to go from a set of files in a repository up to a fully functional Drupal website. The tasks that are executed are set out here:

1. Use Composer to download all the required PHP dependencies: composer install –prefer-dist.
2. Use Drush to install Drupal from a set of configurations.
3. Use the Default Content module to import dummy content.
4. Use Yarn to download all the required JavaScript dependencies and to build the theme assets.

After the build command ends, you can open a browser and start navigating. The website URL is printed at the end of the ddev start command. At any time, you can use the ddev describe command to print a list of details about the project. The URL you’re looking for is the one for the web service:

Figure 1.5 – Using ddev describe to list all the available services for a project

In this case (and probably also for you), the URL is https://packt.ddev.site, and the website should look like this:

Figure 1.6 – The home page of the AlpsTrips website

You’re navigating as an anonymous user; if you want to administer the site, you must log in as a user with some administrative privileges. During the build, one such user has been created for you, with admin as username and admin as password. To log in, you can do the following:

• Click on the Log in menu item
• Navigate to https://packt.ddev.site/user/login

After submitting the credentials, you should see some more elements, such as a dark toolbar at the top of every page. From there, you can access every configuration page of Drupal.

Note

The admin user created during the installation phase of Drupal has too much power. The permissions enforcement and the access checks don’t run for that user. In a real project, we suggest you create a new user, with only the permissions required.

The demo website is packed with everything you will encounter in a standard Drupal website, so let’s explore it and review all the concepts we’ll need to style it.

Frontend development in Drupal usually starts very late in a project life cycle.

The typical steps are reproduced here:

1. The design team has to create mockups, style guides, and the design system.
2. The backend team has to set up the stack, initialize the project, and build the content structure.
3. Some content needs to be created (manually or with some automatic process).
4. Finally, the frontend team works on the frontend.

The main focus of this book is on the last step.

We could try to teach you how the theme layer of Drupal works in an abstract way, without implementing any real theme, or we could start from the first step in the list and make you do a lot of stuff even before you start to understand what a theme is.

We don't think this is the best thing we can do. Instead, we’ll take a little bit of an opinionated approach.

By simulating what happens in a typical project, we have already followed the first three steps for you.

We have implemented a fully configured Drupal 10 website, with a content structure and some example content. We’ve added some other modules that are quite standard in a modern Drupal website, such as Paragraphs (https://www.drupal.org/project/paragraphs).

We have created a design system (https://en.wikipedia.org/wiki/Design_system) and a style guide (https://en.wikipedia.org/wiki/Style_guide).

We’ve also defined how the project should run on your local machine. We’ve chosen for you where the code is hosted, the rules to enforce code quality, and the tools to use.

The demo website has enough features to let us talk about every aspect of the theme layer of Drupal 10, but it’s simple enough to avoid wasting time doing the same thing twice. We have a home page, some listing pages, a detail page, and some forms.

We’ve made a lot of assumptions to allow you to concentrate on the frontend layer only. But don’t worry—we’ll explain every decision we’ve made.

Because of this, the code in the book is not enough to replicate the demo website, so you have to start by cloning the Git repository from GitHub (https://github.com/PacktPublishing/Modernizing-Drupal-10-Theme-Development). We suggest you follow along with the explanations by trying them on your local computer—we’ll guide you step by step.

Let’s start by reviewing how editorial data is managed by Drupal and which concepts we’ll use during the rest of the book.

Fields

All information an editor writes in content using the Drupal admin interface is stored in fields. A field can have different properties, widgets, and formatters. Let’s look at these in a bit more detail:

• Property: Represents the data stored in the database—for example, a text area field has three properties: value, summary, and text format; a geographical field that represents a point on a map probably will have two properties: the latitude and the longitude.
• Widget: An element used by an editor to insert data into the field—for example, a <textarea> HTML element for a text area, or two text fields for a geographical point (to input the latitude and the longitude).
• Formatter: The markup used to show the field value on the frontend so that a user can read it—for example, a formatter for a text area can simply render the text, maybe truncated, whereas a geographical field can be rendered like a marker on a map.

Note

A single field type can have more than one supported widget and more than one supported formatter.

Paragraph types

A paragraph is not a concept that comes from the core of Drupal; it’s contributed by an external module called Paragraphs (https://www.drupal.org/project/paragraphs).

Modern layouts are built by aggregating components, and one possible way to manage such components in Drupal is by using the Paragraphs module.

Paragraphs are a collection of fields that together build a component. For example, a hero paragraph can be made of a background image, a claim, and a CTA button (composed of a label and a URL). A slider paragraph can contain a media field where the editor can insert a list of images to show in a carousel…. and so on.

You can define as many paragraph types as you need to allow editors to compose complex pages.

Content types

Fields and paragraphs are then aggregated into content types. A content type is a collection of fields, such as a paragraph, but with some added features. For example, all content built from a content type has a canonical URL so that it can be added to a menu and navigated by the end user.

Content types are used to represent the different structures an editor can insert into a website, such as a blog post, a landing page, a news page, and so on.

An instance of a content type is called a node.

Vocabulary

Often, it is useful to tag or categorize content, to add information to the end user or for it to be aggregated in some way.

For example, on the demo website, the Trip content type can be tagged by difficulty or by trip duration. To manage this kind of functionality, Drupal provides a taxonomy system, which allows you to manage the vocabulary of terms.

Blocks

Content types (and paragraphs) are not the only way to add editorial content to a website; the block system allows you to put contextual information around the main content—for example, on the header, the footer, or in a sidebar. Blocks are useful because they aren’t related to a specific URL, but they’re shown on a page based on a set of visibility rules. For example, you can place a block on the sidebar of every node of a particular content type, or for every user in a role.

Views

Content is usually aggregated in lists—for example, the latest blog posts or the trips available in a specific season. On a Drupal website, every time you mention a list of something, you’re talking about a view. A view is a collection of elements, extracted from the database using a set of conditions. A view’s output can then be shown at a specific URL or in a block.

Menus

In the end, a website is made of pages that can be navigated by the final user. Pages in Drupal are a mix of nodes, views, and blocks, and the navigation is managed by the menu system. A menu in Drupal is a hierarchical structure that stores a navigation tree. Every element in the tree has a label and a URL, which can be internal or external. A website can have more than one menu—maybe one for the main navigation, one with the user links, one for the footer, and so on.

Before starting to work on the design, we need to do just one more step: disable all the performance optimization that Drupal has out of the box.

Starting from version 8, Drupal is optimized for production out of the box. This means that all cache layers are enabled, and a change in the code is probably not visible until the cache is cleared. Obviously, this can slow down development a lot. In the earlier phases of development, all those optimizations can be turned off, but it is mandatory to turn them all back on before production because running a Drupal site without the cache enabled can hide some very difficult-to-catch bugs. How many times have you heard of data breaches where a legit logged-in user had access to data about some other user? This is probably a cache issue, where a page has been built for a user and then cached and served as is to every other user. If that page contains some personal data, that is leaked to everyone.

Note

Drupal is a complex system; to build a single page, it needs to do a lot of things, and most of them involve some sort of interaction with an external (and usually slow) system (the database for the data, the filesystem for the code, and others). If the markup that Drupal is building can be used as is for multiple requests, it’s a waste of resources to build it over and over again. Cache systems exist precisely to store the intermediate steps of a complex calculation to avoid doing the same thing twice. This text is not part of the note. It must be moved outside, just before the next sentence (At the end...)

At the end of the web/sites/default/settings.php file, we’ve added these lines:

if (
  file_exists($app_root . '/' . $site_path . '/settings.local.php')
  && getenv('IS_DDEV_PROJECT') == 'true'
  )
{
  include $app_root . '/' . $site_path . '/settings.local.php';
}

This basically means that if some conditions are true, the system should include a configuration file with local settings. The conditions are set out here:

• Check whether the $app_root . '/' . $site_path . '/settings.local.php' file exists. app_root resolves to the /var/www/html/web folder, and site_path resolves to the sites/default folder
• Check whether the value of the IS_DDEV_PROJECT environment variable is true

Both conditions are true on our local stack; the file it’s located at /var/www/html/web/sites/default/settings.local.php and its content has been copied from /var/www/html/web/sites/example.settings.local.php, with a couple of lines uncommented. Let’s see the most important ones:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';

Drupal organizes all the business logic into services, discrete PHP classes that perform a specific task (such as sending an email, rendering a template, writing to logs, and so on). All those services are managed by a service container (https://symfony.com/doc/current/service_container.html). When some code needs a service to perform a task, it asks the service container to provide one, along with all its dependencies. The service container also manages parameters, which are scalar values that can be used to configure the application.

One of the services defined in the service container manages the integration with a cache backend.

A cache backend is used to store data that is slow to be computed. Instead of executing the same slow code on every request, Drupal can store the results in a cache. This speeds up the building and delivery of pages.

By default, the cache backend is the same database that Drupal uses for content (managed by a service called cache.backend.database). Every time Drupal needs to save some intermediate computation, it passes the data to the cache system, which in turn uses the cache backend to persist it somewhere.

We can use the development.services.yml file to add or change services and parameters in the service container. Let’s break down the file to see what it does:

parameters:
  http.response.debug_cacheability_headers: true

This parameter forces Drupal to add a couple of HTTP headers to the response. This will be useful later when we talk about cache tags.

twig.config:
  debug: true
  cache: false

Those two lines configure Twig (Twig is the render engine that turns templates and data into HTML), by enabling debug and disabling the cache.

services:
  cache.backend.null:
  class: Drupal\Core\Cache\NullBackendFactory

Lastly, here we define a new cache backend service, cache.backend.null, which uses the NullBackendFactory class to manage the cache. NullBackendFactory doesn’t persist the cache anywhere, basically forcing Drupal to rebuild its data structures on every request.

Continuing with the settings.local.php file, we find the following:

$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;

Those two lines disable the CSS and JavaScript preprocessing and minification system of Drupal. When preprocessing is TRUE, if you look at the source of any Drupal page, you will see something like this:

<link rel="stylesheet" media="all" href="/sites/default/files/css/css_4X4pNrCAbSu81rOnCPB9UMoipKt5NIfi5kpoa86bdG8.css" />
<link rel="stylesheet" media="all" href="/sites/default/files/css/css__4bA7B8aKHQdv-woFVLAGpXcUrTGif-jwiZJPj5yZ1s.css" />
<script src="/sites/default/files/js/js_Y151moVVESM9BeoCt8M3cSJ2_x_o14H43dXy6nGL6JM.js"></script>

This is difficult to understand because isn’t clear where a CSS rule or a JavaScript function comes from (also because the CSS in those files are minified). When preprocessing is FALSE, the output is way more readable:

<link rel="stylesheet" media="all" href="/core/themes/stable9/css/system/components/ajax-progress.module.css?rmstqh" />
<link rel="stylesheet" media="all" href="/core/themes/stable9/css/system/components/align.module.css?rmstqh" />
<link rel="stylesheet" media="all" href="/core/themes/stable9/css/system/components/autocomplete-loading.module.css?rmstqh" />

In the preprocessed version, the filename changes every time the cache is cleared, and this forces the browser to download the file again. When preprocessing is turned off, Drupal emits the original name of the file. To force the browser to download the file again, a token is appended at the end.

Three more lines deserve attention in settings.local.php:

$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['page'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Those lines are commented in the original example.settings.local.php file. By removing the comments, we force the cache bins that deal with HTML generation to use the cache.backend.null service that we added in the default.services.yml file.

Note

Starting from Drupal 10.1 there is an easier way to manage development settings. A new Configuration | Development settings page has been added that allows you to turn on Twig development mode and to turn off render cache, dynamic page cache, and page cache. You can find more information on the related change record here: https://www.drupal.org/node/3359728.

Enabling Twig debug and disabling caches slow down the website but will allow us to see a change in template as soon as we reload a page, without the need to clear the cache. As we mentioned before, the functionalities of the website must be tested with those caches enabled, as they will be in production, to avoid possible data leaks.

In this chapter, we learned an easy way to set up a local machine to work on a Drupal 10 website. Using Docker and DDEV, we installed the website we’ll work on for the rest of the book. We also installed and set up an IDE, Visual Studio Code, which will allow us to inspect and work on the code in a powerful way. We dissected the demo website to recap how a Drupal website is made and which concepts we need to understand it. Finally, we disabled all the performance optimization to speed up the development of the new custom theme.

It's time to start building our theme. In Chapter 2, Setting a New Theme and Build Process, we'll create a new theme from scratch and set up a build process to automate some useful tasks.