How Drupal Renders an HTML Page

In this chapter, we’ll start to dive into the layers of Drupal that deal with the frontend.

You will learn where a page comes from, how it is assembled, and by which parts. We’ll see what a template is and how it is used by Drupal (and Twig) to deliver an HTML page. Then we’ll talk about theme hooks and render arrays, the structures that Drupal has to mix templates and contents together.

Additionally, you will learn how to define a library to attach custom CSS and JavaScript files to a page.

Finally, you will see how to deliver the content of a controller action as a dialog.

By the end of the chapter, you’ll master the render pipeline of Drupal, and you’ll understand how Drupal builds all its pages.

This chapter will review the following key topics:

• What is a template?
• What is a render array?
• Controllers and blocks
• How to inject CSS and JavaScript into a template
• Alternate ways...

What is a template?

As we’ve already mentioned, one of the strengths of Drupal is the clean separation between where the content is created and where it is converted into HTML pages. This is possible because, internally, Drupal uses a render engine that is capable of merging data and markup.

That render engine is Twig.

WebProfiler

The internal workings of Drupal are complex, and there is sparse documentation about how it works on the internet. To simplify our work as a Drupal Themer, we may need a tool that collects useful data from the content management system (CMS).

The Drupal contributed (contrib) module WebProfiler is what we’re looking for. Let’s install it using Composer:

ddev composer require drupal/webprofiler

After the download completes, we can enable it with Drush:

ddev drush pm:enable webprofiler

WebProfiler depends on Devel, another useful module that we’ll use in the coming sections.

If you now log in as an admin...

What is a render array?

Drupal’s theme system allows a theme to have nearly complete control over the appearance of the site, encompassing both the CSS responsible for styling the markup and the markup itself. Essentially, the system mandates that modules utilize render arrays instead of coding HTML markup directly. Render arrays are multidimensional arrays that contain both the rendering data to be transformed into HTML and the options that influence the markup.

Each level in the hierarchy of a render array (including the outermost array) has one or more array elements. Array elements whose names start with # are known as properties, and the array elements with other names are children (constituting the next level of the hierarchy); the names of children are flexible, while property names are specific to the type of data being rendered.

For example, a render array that uses our theme hook, along with the data that should be passed to it, can be the following:

[
 ...

How to inject CSS and JavaScript into a template

Now we want to add some default styles and some interactions to our template, and to do that, we need a CSS file and a JavaScript file. To wrap those files together and attach them to the render array, you need to define a library.

Libraries

Libraries are defined in YML files, both by modules and themes. To add a library to the weather module, we need to create an alps_weather.libraries.yml file in the module’s folder with this content:

base:
  version: 1.0.0
  css:
    component:
      css/alps_weather.css: {}
  js:
    js/alps_weather.js: {}
  dependencies:
    - core/drupal
    - core/jquery
    - core/once

In this file, we define a new library called alps_weather/base because the library identifier consists of the machine name of the module and...

Alternate ways to render a controller action output

We may need to do something more complex than opening a popup with some static text. Maybe we can show more data about a specific weather forecast, such as pressure, humidity, and wind speed.

We need to define a new controller action to render the details of a forecast for a specific city at a specific date and time. The controller action will use a new theme hook to render a set of detailed information:

function alps_weather_theme(): array {
  return [
    [...]
    'alps_weather_details' => [
      'variables' => [
        'forecast' => [],
        'units' => 'metric',
      ],
    ],
  ];
}

The alps_weather_details theme hook takes the same variables...

Summary

In this chapter, we explored how Drupal builds a page in every aspect. Starting from how to define a template and moving all the way to how to use it to render a section of a page, we’ve built our first controller action.

We then saw how controllers and blocks are used to populate the regions of a theme.

You then learned how to attach CSS and JavaScript files to a template by defining and using a library.

Finally, we also discovered how to render the output of a controller action in a dialog by loading its content with an AJAX call and without writing a single line of JavaScript.

Now that you know how the internals work and the Drupal render pipeline doesn't hold any secrets, we can start styling the demo website. In Chapter 4, Mapping the Design to Drupal Components, we'll analyze materials provided by the design team to see how it fits in our Drupal site.