Documentation AEM as a Cloud Service User Guide

Configuring the Layout Container and Layout Mode

Last update: February 10, 2025

Topics:
Administering

CREATED FOR:

Admin

Learn how to configure layout container and layout mode to enable responsive layouts for your content authors.

TIP

This document describes how a site administrator can configure the layout container to support responsive web design. Additional resources are available:

For content authors, details of how to use responsive design features on a content page are available in the document Responsive Layout.
For developers, details of the Layout Container and the responsive grid are described in the The Responsive Design document, which provides and tips for using layout containers and responsive grid when designing your site.

Overview

Responsive Layout is a mechanism for realizing responsive web design. This allows the content author to create web pages that have a layout and dimensions dependent on the devices their users use.

AEM realizes responsive layout for your pages using a combination of mechanisms:

Layout Container - This component provides a grid-paragraph system that allows you to add and position components within a responsive grid.
- It can be used as the default parsys for your page and/or made available to authors in the component browser.
- The default Layout Container component is defined under /libs/wcm/foundation/components/responsivegrid.
- You can define layout containers:
  - As a component that the user can add to a page.
  - As the default parsys for the page.
  - As both a component and the default parsys.
    - You can have the layout container as standard for the page, while allowing the user to add further layout containers within this; for example, to achieve column control.
Layout Mode - Once the layout container is positioned on your page you can use the Layout mode to position content within the responsive grid.
Emulator - This allows you to create and edit responsive websites that rearrange the layout according to device/window size by resizing components interactively. The user can then see how the content is rendered using the emulator.

With these responsive grid mechanisms you can:

Use breakpoints (that indicate device grouping) to define differing content behavior based on device layout.
Hide components based on device group (define on which breakpoint a component will be hidden).
Use horizontal snap to grid (place components into the grid, resize as required, define when they should collapse/reflow to be side-by-side or above/below).
Realize column control.

NOTE

When creating a site from the Project Archetype or from the Standard Site Template, the responsive layout is generally configured. Otherwise, you must activate the Layout Container component for your pages.

Enabling the Emulator

The Project Archetype and the Standard Site Template are already enabled to use the emulator. If you have developed your own content not based on the Core Components or archetype, please see the document Responsive Design for details on how to develop your components while leveraging these features.

Activate Layout Mode for your Site

Layout mode allows you to use the emulator to adjust the layout of your content for different devices. The WKND sample site is already enabled for Layout mode. Follow these steps to enable your own site.

Configure Breakpoints

Breakpoints are vital to responsive design and define how and when content is adjusted to the target device. However, be cautious since each breakpoint you introduce will generate additional work for your authors to accommodate the content. Many times, two breakpoints can be sufficient, including the default breakpoint which is always there. Adobe recommends not to create more than three breakpoints including the default, i.e. not more than two nodes below cq:responsive/breakpoint.

Breakpoints have a title and a width:
- The title describes the generic device grouping, with orientation if necessary.
  - For example, phone, tablet
- The width defines the maximum width in pixels for that generic device grouping.
  - For example, if the breakpoint phone has a width of 768 then that it the maximum width of the layout used for a phone device.
Breakpoints can be defined:
- On the page template, from where the settings are copied to any pages created with that template.
- On the page node, from where the settings are inherited by any child pages.
Breakpoints are visible as markers at the top of the page editor when you are using the emulator.
Breakpoints are inherited from the parent node hierarchy and can be overridden at will.
There is a default (out-of-the-box) breakpoint which covers everything above the last configured breakpoint.
Breakpoints can be defined using CRXDE Lite or XML.

Breakpoints should be considered for both new and existing projects.

If you are setting up a new project, you should add breakpoints to the templates.
If you are migrating an existing project (with existing content), you must:
- Add breakpoints to the templates.
- Add the same breakpoints to the existing pages.

Because of inheritance you only have to do this for the root page of your content.

Configuring Breakpoints using CRXDE Lite

Using CRXDE Lite, navigate to either:
- Your template definition.
- The jcr:content node of your page.
Under jcr:content create the node:
- Name: cq:responsive
- Type: nt:unstructured
Under this create the node:
- Name: breakpoints
- Type: nt:unstructured
Under the breakpoints node you can create any number of breakpoints. Each definition is a single node with the following properties:
- Name: <descriptive name>
- Type: nt:unstructured
- Title: String <descriptive title seen in Emulator>
- Width: Decimal <value of breakpoint>

Configuring Breakpoints using XML

Breakpoints are located inside the <jcr:content> section of the .context.html under the appropriate template (or content) folder.

An example definition:

<cq:responsive jcr:primaryType="nt:unstructured">
  <breakpoints jcr:primaryType="nt:unstructured">
    <phone jcr:primaryType="nt:unstructured" title="{String}Phone" width="{Decimal}768"/>
    <tablet jcr:primaryType="nt:unstructured" title="{String}Tablet" width="{Decimal}1200"/>
  </breakpoints>
</cq:responsive>

Enable Component Resizing for the Page

Resizing components in Layout mode is an important part of responsive design, which can be used in the WKND sample site. Follow these steps to enable your own site.

Set Layout Container as Main Parsys

To set the main parsys of your page to be a layout container, define the parsys as:

wcm/foundation/components/responsivegrid

In either the:

Page component
Page template (for future use)

The following two examples illustrate the definition:

HTL:

<sly data-sly-resource="${'par' @ resourceType='wcm/foundation/components/responsivegrid'}/>

JSP:

<cq:include path="par" resourceType="wcm/foundation/components/responsivegrid" />

Include the Responsive CSS

CSS for Breakpoints using LESS

AEM uses LESS to generate parts of the necessary CSS, these need to be included for your projects.

You must create a client library to provide additional configuration and function calls. The following LESS extract is an example of the minimum that you must add to your project:

@import (once) "/libs/wcm/foundation/clientlibs/grid/grid_base.less";

/* maximum amount of grid cells to be provided */
@max_col: 12;

/* default breakpoint */
.aem-Grid {
  .generate-grid(default, @max_col);
}

/* phone breakpoint */
@media (max-width: 768px) {
  .aem-Grid {
    .generate-grid(phone, @max_col);
  }
}

/* tablet breakpoint */
@media (min-width: 769px) and (max-width: 1200px) {
  .aem-Grid {
    .generate-grid(tablet, @max_col);
  }
}

The base grid definition can be found under:

/libs/wcm/foundation/clientlibs/grid/grid_base.less

Styling Considerations

Components held within a responsive container are resized (together with their respective HTML DOM elements) according to the responsive grid size. Therefore, in these circumstances, it is recommended to avoid (or update) definitions of fixed width (contained) DOM elements.

For example:

Before:
- width=100px
After:
- max-width=100px

Resizing and Adaptive Image Compliance

Any resizing of a component within the grid will trigger the following listeners as appropriate:

beforeedit
beforechildedit
afteredit
afterchildedit

To properly resize and update the content of an adaptive image included in a responsive grid, you need to add an afterEdit set to REFRESH_PAGE listener into the EditConfig file of every contained component.

For example:

<cq:listeners jcr:primaryType="cq:EditListenersConfig" afteredit="REFRESH_PAGE" />

The adaptive image mechanism is made available via a script that controls selection of the correct image for the current size of the window. It activates after the DOM is ready or when receiving a dedicated event. Currently the page must be refreshed to properly reflect the result of the user’s action.

CAUTION

Custom stylesheet clientlibs must be loaded as part of the header for them to work properly on author as well as publish.

Enable the Layout Container Component for Page

For effective responsive layout, the content author must be able to drag instances of the Layout Container component onto the page. This is already enabled for the WKND sample site. Follow these steps to enable your own site.

Enable the Layout Container Component for Page Editing

To allow authors to add further responsive grids to the content pages you need to enable the Layout Container component for your page. You can do this using either:

Via the Author Environment - Edit your page templates to enable the Layout Container for a page.
Component Definition - Use allowedComponent or a static include when defining the component.

Configure the Grid of the Layout Container

You can configure the number of columns available for each specific instance of layout container by editing your page templates.

Nested Responsive Grids

Adobe’s recommended best practice is to keep the structure as flat as possible.

When you can not avoid using nested responsive grids, please see the developer document Responsive Design.

recommendation-more-help