Layout Builder
This chapter is about configuring media.
Table of contents
Drupal core module discussed in this chapter: Layout Builder.
Introduction
The Layout Builder module for Drupal provides a layout user interface (UI), a set of flexible visual design tools that allows content creators and site administrators to customize the layout of a page via a powerful drag-and-drop UI. You can use Layout Builder to customize the layout of a single page, create a custom layout for all content of a certain type, or build landing pages.
At a high level it allows users to generate a layout -- two columns with a header, for example -- and then place a content type's fields and any blocks into that layout.
One of the most commonly requested features over the years has been for Drupal to provide some kind of easy-to-use page builder with a WYSIWYG sort of experience. These tools are present in other platforms, and can allow for far more flexibility without the need to write code. Such a tool can empower a whole new category of Drupal users to customize the look and feel of their Drupal applications.
To address this demand, contributed modules such as Panels and Display Suite filled the gap. But solutions using these modules were often incompatible with one another. Layout Builder (in Drupal core), provides a consistent API for modules to register a layout, and define what layouts are and can do. Moving this responsibility to core helps to unify the contributed module ecosystem rather than having lots of different silos.
Layout Builder in Drupal core consists of two modules:
- Layout Discovery: An API module that defines what a layout is and handles layout registration and rendering. It also includes utilities such as automatically generating icons for the UI and more.
- Layout Builder: A drag-and-drop UI for creating flexible layouts for content types built on top of the Layout Discovery API. The Layout Builder UI allows site administrators to configure a layout to use when displaying a content type, and then arrange the content types fields within the layout. Layout Builder can also place any block into a layout, which opens up all kinds of possibilities.
Layout Builder capabilities
Layout Builder module works with the fields of a specific content type, blocks, and block types.
In the simplest setup, a site builder creates a layout for a content type and applies the layout to all nodes of that content type. If they make changes to the layout, the changes apply to all existing and newly-created nodes of that type. Configuration options allow the site builder to specify a default layout for a content type, while allowing per-node customization of that layout.
Layout Builder defines two main concepts used when creating a layout:
- Section: Sections are the containers into which we place blocks. A example of such a container is a column in a 2-column layout. Each layout can have as many sections as required, but must have at least one. Sections create the skeleton of the layout. Once we define the sections, we cannot move them around.
- Block: A block is a content element that we can place into a layout. We place blocks in sections. Blocks represent the content that will appear there.
It's important to understand that a block inside Layout Builder is not the same thing as a standard Drupal block entity. It has a more abstract definition and acts more like a placeholder indicating that something goes here.
One example is a block that creates a wrapper for the fields of a content type. When we associate a layout with a content type, these blocks can placed into the sections for that "layout + content type" combination. Since they're specific to the content type these blocks wouldn't be available for the same layout on a different content type.
Depending on the field type, the block exposes the appropriate field formatter configuration. It's much like the Manage display settings for a content type not using the Layout Builder.
The second type of block available within the Layout Builder are block entities. All custom blocks configured for your site, and all module-provided blocks, are available to use within the Layout Builder.
This opens up a variety of options. For example, the ctools module exposes views and view modes for the content type. The facets module allows you to place facets blocks inside the layout builder, and the system module allows you to place the "Powered by Drupal" block, breadcrumbs, content and messages. You can also author your own custom block plugins to provide any content you need. Any custom block plugins you create will be available in Layout Builder.
Layout Builder creates flat layouts. That is, it doesn't allow for the nesting of sections, or blocks.
The Layout Builder UI allows editors to preview their layouts using real content. You can toggle between a generic layout screen and one with preview content entered.
Extending Layout Builder
The Layout Builder module is still in active development. The Drupal community is working on features and enhancements to its functionality. If you find yourself in a situation where the module doesn't do certain things that might be useful, chances are high that other people in the Drupal community also thought the same thing. There may already be a contributed module that extends the current Layout Builder functionality and solves the problem you're facing.
Find the complete list of modules that work with Layout Builder on Drupal.org.
The most popular contributed modules that are actively maintained and promoted by the community are solving problems of enhancing the editorial experience by simplifying and decluttering the UI. They allow things like hiding blocks that should not be available for placement within the layouts, and making certain layouts accessible to specific content types.
Some modules provide different options for the layout and appearance of the right control panel of the Layout Builder UI. All these options improve usability of the Layout Builder interface and editorial workflow.
An evolving toolset
Layout Discovery module, layout API and Layout Builder are products of the Drupal layout initiative. The initiative's goal is, "to provide site builders and content authors with intuitive tools to build pages, change layouts, and add and rearrange blocks with live preview." It's one of the main strategic initiatives active in the Drupal community.
The current challenge is working with multilingual websites; translation of specific layouts is not yet supported.
You can get an overview of the current state of things by browsing the issue queue for related issues. Often, you will find existing solutions to issues you encounter.
We think the existing tools are production-ready, but you might find some rough edges as you go.
Recap
The Layout Builder ecosystem is the newest addition of layout construction tools available in Drupal core. It consists of 2 primary modules in Drupal core: Layout Discovery, which allows modules and themes to declare their custom layouts, and Layout Builder, which provides a visual design tool that allows the construction of layouts without writing custom code. In addition, there are a growing number of contributed modules that seek to improve the UX of the existing core modules.
Layout Builder is stable, but is still a work in progress. The Drupal community has resolved some of the immediate problems through contributed projects, while patches available in specific issues mitigate other problems.
Enable the modules
We're going to define a new layout for the Basic page content type that has two columns at the top, and a single column below. We'll place the page-specific author and publication date in the top left column, a generic call-to-action block in the right column, and the main content of the page in the single bottom column.
Enable Layout Builder and Layout Discovery modules
In the Manage administration menu, navigate to , then check the Layout Builder and Layout Discovery modules. Select "Install" to enable them.
Enable Layout Builder for a content type and change the configuration
We will enable Layout Builder for the Article content type.
Navigate to , then select "Manage Display" for Article under "Operations".
While there's no explicit restriction about what view mode to use, the module's purpse is to set up and manage layouts for pages. We recommend using the "Default" view when setting up a layout.
Locate "Layout options" section. In this section check "Use Layout Builder". Leave "Allow each content item to have its layout customized" unchecked. Press "Save".
Switch to Layout Builder UI for the Article content type
Once you've saved the configuration, you should see that all fields disappear and a "Manage layout" button appears.
Turn off content preview
Press the "Manage layout" button. You will now be shown a preview of one of your Articles.
Since we are editing the layout for the entire content type, and not for a particular node, Drupal also creates some placeholder content for editors to see and envision how the layout will be applied.
If you find the preview content makes it harder to manipulate the layout, it is possible to turn it off and see block and field labels instead. Let's hide the demo content by unchecking "Show content".
Now we can see field labels and gain a better understanding of what was placed and where. You should see something like shown below:
PICTURE
Change base configuration
Layout Builder module created a one-column layout with a single section named "Section 1". It is a good idea to name sections something more meaningful so it's easier to understand their purpose later. To change the section's name and configuration click the "Configure Section 1" link. When the configuration pane is open, give the section administrative label of "Main Content" and press "Update".
You should see that the section changed the label to "Main Content" in the UI.
Based on the layout settings the configuration options for sections may differ. For example, the width of columns is a configuration option. We will explore additional configuration options in the next step.
Add a two-column section to the layout
Layout Builder comes with some predefined layouts that can be used within the interface. We have already seen the One column layout. To explore other options available out of the box, click the top "+ Add Section" link.
This opens a configuration pane that lists all available layouts and icons that demonstrate their structure.
Selecting an icon will create a new section within the page above the already existing "Main Content" section and open configuration options for it.
Select the Two column icon. You should see that this section's configuration now has column width settings. Select the 25%/75% option, name the section "Content Prefix" and select Add Section. We can always come back and change these settings later if they end up not working for our content and presentation goals.
Now we have a new section above the Main Content one.
As you have seen during the creation of the "Two column" section, by default the Layout Builder module defines four different layouts from one column to four columns. The sections can mix and match within the main page container, but once placed they cannot be moved around. If you'd like to move the section somewhere else, for example move the Content Prefix section below the Main Content, we would need to delete the section and create a new one instead of dragging it under the one column section.
There's ongoing work to resolve this limitation.
Add field blocks to the left 25% wide section
To render content for the end user we need to place blocks inside the defined sections. In the Layout Builder interface, every field associated with a content type has a block wrapper and is treated as a block (even though it may not be a Drupal block per se).
When working with content fields and placing them inside the Layout Builder, you give them a block content wrapper.
Let's use our newly created section and place some fields in there. First, select the + Add block button in the left 25% wide section. In the section Content fields select Authored by field and configure it to not show labels and set the formatter to be Author.
PICTURE
When done, press "Add block".
Repeat these steps one more time but now select Authored on field. Now you should have Authored on and Authored by field blocks placed one under another in the left narrow column of our layout.
Drag Authored on block to appear above Authored by block. Notice that you can drag-and-drop blocks not only within one section but also across all sections in the layout.
Settings for each block can be updated by hovering over the block and selecting the pencil icon to open the contextual menu for the specific block.
It's important to note that since the blocks within the Layout Builder are not standard Block plugins, the typical block configuration options are not available here. Instead you have an interface that contains the settings for the field widget or any other entity wrapped in the block.
Add custom blocks to the right 75% wide section
We have created an authoring information section. Now let's imagine that every Article has to have a Call To Action (CTA) to the newsletter. Since this CTA is common across all Articles it makes sense to use a custom block for its content storage instead of reentering this information in every node edit form.
Select + Add block in the right column and select + Create custom block button at the top of the configuration pane. This opens a new interface that consists of the same options as the interface we see when creating custom basic blocks in the custom block administration UI. Populate the content and title of your new CTA block and select Add block.
Save the layout
We have finished all required changes for this exercise. But the changes are not saved yet. Select the Save layout button near the top of the page to save this layout and apply it to every Basic page node rendered using the Default view mode.
Once the save is successful you'll be taken back to the Manage display tab, and you should see a message saying, "The layout has been saved."
Test the new layout
Let's give it a try. Navigate to the Content menu, select Add content and choose Article. Populate the content for the node and save the node. Once it's saved you should see something like the result below.
PICTURE
As you can see we populated the Body and Title of the node. The CTA was pulled from the main layout for Basic Page content type.
Note: Even though the CTA block is a custom Drupal block, it's considered content not configuration. If you navigate to Structure > Block layout > Custom block library (admin/structure/block/block-content) you will not see it in the list of available blocks. You also won't be able to place it as a typical block in a theme region through the Block layout interface.
If you'd like the blocks created within the Layout Builder interface to be reusable you may want to look at this issue.
Final word
d.me.
Last update: 2022-04-16 [gh].