A first look at layouts in Drupal core

Today, I started looking at some of the proposals to include layouts within Drupal core from version 8.3 onwards.

This initiative aims to take the functionality that currently exists for laying out blocks and regions, and to use it for displaying other things, such as content entity view and form modes.

Some of this work started life in contrib, in the layout plugin module. Although this module is still alpha status, both the panels and display suite modules use it. Those modules can, therefore, share layouts. However, this module seems to be a stepping stone for what will eventually end up as a core module. Somewhat confusingly, it has a different name.

I’ve decided to focus only on two small modules, either in or planned for Drupal core:

Layout discovery module

Layout discovery is currently in Drupal 8.3 as an experimental module.

This is a very simple API module that allows for the discovery of layouts provided by other modules. It replaces the Layout plugin module mentioned above.

Providing your own layouts is pretty straightforward and documented. The most basic use case is a YAML file that defines a layout and it’s regions, along with a corresponding twig template. More complicated stuff can be done too - a dynamic layout builder would provide the layout definitions to be discovered by this module too, but probably by implementing a deriver class.

I was able to create a very simple layout with ease:

two_column:
  label: Two column
  category: Erik's layouts
  template: templates/two-column
  regions:
    main:
      label: Main content
    secondary:
      label: Secondary content

The template is equally easy, just put the markup you want for the layout and then refer to {{ content.main }} and {{ content.secondary }} in the appropriate places.

Field layout module

Field layout is a proposed new module, not yet added to Drupal core. [Update: as of 26 Jan this is now part of Drupal core]

This alters the manage display and manage form display settings forms. Currently a Drupal site builder can use these forms to control the ordering in which each field is displayed. If you want to do anything more involved, you need to write a twig template for a particular display. The field layout module enhances this, allowing the site builder to choose a predefined layout and populate it’s regions with fields.

Think of it as a cut down version of display suite.

Rendering

I studied the field layout module to see how it works, and how I might use layouts in other settings. It turns out rendering a layout programmatically is quite straightforward. To use the two_column layout defined above, my render array would look like this:

$output = [
  '#theme' => 'layout__two_col',
  'main' => [ /* render array for main content */ ],
  'secondary' => [ /* render array for secondary content */ ],
];

I think this is going to be really useful to have in Drupal core.