Layouts

As part of the Drupal 8 release cycle, the Layouts API has been introduced in order to provide contributed modules with a unified approach for defining layouts. For example, modules such as Panels and Layout Builder make use of this API to define layouts that contain regions and that can render content and all sorts of things inside.

Layouts were introduced in version 8.3 of Drupal as an experimental module (called Layout Discovery) and marked stable in version 8.4. At the same time, a new experimental module has been introduced, called Layout Builder, which uses this API to provide site builders a way to build layouts for regular content. And since Drupal 8.8, the latter has also been marked as stable.

We won't be using layouts going forward in this book but it's important you know how to work with them in case you need them. So let's quickly talk about how you, as a module developer, can define and make use of layouts programmatically.

Defining layouts

Simply put, layouts are plugins. But unlike the plugins we've seen before, these are defined in YAML files instead of annotations above a class. One of the reasons for this is that layouts are more definition than functionality, so they don't necessarily require classes. They can be simply defined in a few lines inside a YAML file.

Although not necessarily, YAML-based plugins are typically defined inside a file named module_name.plugin_type_name.yml found in the root of the module defining the plugin. So in the case of layouts, this would be module_name.layouts.yml. But what does a definition contain?

Let's imagine we want to define a two-column layout with a left and right region. Our simplest definition could look like this:

two_column:

  label: 'Two column'

  category: 'My Layouts'

  template: templates/two-column

  regions:

    left:

      label: Left region

    right:

      label: Right region

So what do we learn from this definition?

• First, we have a name and category, which are mandatory. These can be used in whatever UI to show information about the layout.
• Second, we specify the template that should render this layout. The corresponding theme hook gets defined under the hood. In the case above, the template file would be in the templates folder and would be called two-column.html.twig.
• Lastly, we define the regions of the layout with a label for each. The left and right keys are important as they are the machine names of the regions.
• As a bonus, if we wanted to attach a library, we could add another line to this definition, like so:

library: my_module/my_library

Before the layout registration is complete, we'd also need to create the template file we referenced. And it could look like this:

<p class="two-column">

  <p class="left-region">

    {{ content.left }}

  </p>

  <p class="right-region">

    {{ content.right }}

  </p>

</p>

In the template we have access to the content variable on which we can access the values of the regions we can print.

And that's pretty much it. Clearing the cache (and enabling the Layout Discovery module) would register this layout with the system.

Rendering a layout

OK, but registering a layout doesn't help us with much. Unless, of course, we use Layout Builder or some contributed module that uses layouts for various things. In which case we'd already be providing great value. But what if we want to use this layout ourselves? In other words, render stuff with it.

The simplest way of rendering something with this layout could look like this:

$layoutPluginManager = \Drupal::service('plugin.manager.core.layout');

$layout = $layoutPluginManager->createInstance('two_column');

$regions = [

  'left' => [

    '#markup' => 'my left content',

  ],

  'right' => [

    '#markup' => 'my right content',

  ],

];

return $layout->build($regions);

Without going into too much detail about the plugin system (yet), but with the above we use the Layout plugin manager to create a new instance of the layout we defined (whose machine name is two_column). Then we prepare the data to print inside the layout in the $regions array. As you can see, the array construct mirrors the regions in the layout. Finally, we build the layout by passing the regions data. And that is it. The resulting render array would render the template with the content printed in the corresponding regions.