Layout Builder Best Practices

reviewed 240506

At Kalamuna we use view modes whenever possible when working with layout builder. Here are a couple of standard guidelines that we use during the setup. We try to limit use of fields and instead combine fields into view modes that can be used later and placed within layout builder sections using CTools module and entity display blocks. Avoid placing fields when possible. Enable Layout Builder only on the content types and view modes where it’s needed. Allow override of individual layouts on marketing content types such as Basic Pages and Landing Pages.

Sections Setup

We setup custom sections and unset core sections. The reason is so we can have custom templates and full control of what is available to the end user.

To setup sections for your projects, follow these steps:

In [yourtheme].layouts.yml file define the layouts.

2_columns:
  label: '2 Columns'
  template: templates/layout/two-columns
  category: 'TFI'
  icon_map:
    - [column1, column2]
  regions:
    column1:
      label: First Column
    column2:
      label: Second Column

Make sure you specify label, icon map and regions, please include custom template in the templates/layout directory. An example template is as follows:

{##
 * Layout template for columns.
 *
 ##}
{%
  set classes = [
    'layout',
    'two-columns',
    'columns',
    'layout-builder__region'
  ]
%}
{{ attach_library('tfi_layouts/layouts') }}
<div class="layout-container">
  {% if content.column1|render or content.column2|render %}
  {% if content.title %}
  <div class="{{ content.title.attributes.class|join(" ") }}">
    {% if content.title.wrapper %}<{{ content.title.wrapper }}>{% endif %}
    {{- content.title.label -}}
    {% if content.title.wrapper %}</{{ content.title.wrapper }}>{% endif %}
  </div>
  {% endif %}
  <div {{ attributes.addClass(classes) }}>
    {% if content.column1|render %}
      <div {{ region_attributes.column1.addClass('column-1') }}>{{ content.column1 }}</div>
    {% endif %}
    {% if content.column2|render %}
      <div {{ region_attributes.column2.addClass('column-2') }}>{{ content.column2 }}</div>
    {% endif %}
  </div>
  {% endif %}
</div>

Update sub-section names, include default layout builder region classes layout-builder__region and region_attributes. Those templates are starting points and can be refined more in the styling phase of the project.

Unset core layouts. All core layouts except one column need to be unset. You can do it in the hook.

/**
 * Implements hook_layout_alter().
 */
function [yourtheme]_layouts_layout_alter(&$definitions) {
  $remove_layouts = [
    'layout_twocol_section',
    'layout_threecol_section',
    'layout_fourcol_section',
    'layout_twocol',
    'layout_builder_blank'
  ];

  foreach ($remove_layouts as $layout_key) {
    unset($definitions[$layout_key]);
  }
}

Place the hook in your .theme file.

Setup Layout Back-end library. In your [yourtheme].libraries.yml setup the following definition:

In the sass folder, add layouts.scss partial with the following styles:

Ensure the library is attached in the Twig template, as shown in the example template. The Front-end developer will update the theme compilation to compile layouts.css.

Modules Setup

Install the following modules:

Layout Builder Styles
Layout Builder Sections Config
CTools
CTools Views
CTools Blocks
Layout Builder Modal
Layout Builder Admin Theme (Optional)
Layout Builder Restrictions
Layout Builder Asymmetric Translation

Layout Builder Styles

^ configure them to use styles for sections as specified in your design document, group styles into groups for spacing, background etc.

^ Configure individual styles. Limit them to sections or block types as described in the components breakdown document

^ will be available on blocks

^ will be available on sections.

^ select appropriate sections

Layout Builder Sections Config

(admin/config/content/layout-builder-sections-config)

^ Specify tag labels and position options as per the components breakdown document.

CTools Modules

(CTools, CTools Views, CTools Blocks)

^ they will be needed when you work with blocks within the layout

Layout Builder Modal

^ No config is needed; it improves editorial experience. Optionally, you may visit ‘/admin/config/user-interface/layout-builder-modal' to change some settings, but the default work out of the box.

^ Theme dropdown: You may pick ‘Admin theme(Seven)' if you find the frontend theme is causing issues.

Layout Builder Admin Theme (Optional)

Visit ‘/admin/config/content/lbat’

^ enable to force layout builder to use admin theme if frontend theme is causing issues.

Layout Builder Restrictions

^ Configure only needed blocks and block types, disallow default system blocks, views that are not going to be used, fields that shouldn’t be part of the Layout Builder setup.

Layout Builder Asymmetric Translation

^ Install and ensure that the translation is working.

View Modes Setup

Setup view modes for each block as described in the components document. No need to override templates. The front-end developer will do it.

^ slider will be rendered as a view mode inside the default layout

Review History

Who	When	Status

Who	When	Status
Anya	20240506	Current