How to Implement a Responsive Layout in AEM part 5


Welcome to the end of our five part series titled “How to Implement a Responsive Layout in AEM”, if you haven’t read the previous articles please do so before reading this article.

This article will cover the more advanced options of the responsive layouting system. This information will help you customize your experience even further. It will also aid in understanding the finer aspects of the system, and how to use them to their fullest potential.

Breakpoints and Emulators: What Are They and How to Use Them
The following section concerns the defining and use of breakpoints. More information on this topic can be found here. These breakpoints define the maximum size screen. Screens that are smaller than this size will be displayed using the breakpoint that is immediately greater than or equal to the viewport size. Size is defined as the “width” property inside the breakpoint node.

Making a new breakpoint:

  1. Add a new node to /content/[new_page]/jcr:content/cq:responsive/breakpoints.
    1. Defining the jcr:primaryType as nt:unstructured.
    2. The Name of the node must be unique from all other breakpoints defined in /content/[new_page]/jcr:content/cq:responsive/breakpoints, and should be descriptive of its intended use.
  2. Add a property to the node with the Name “title” and the property Type of “String”.
    1. The Value of this property is what is displayed in the emulator and, as such, should be a short but descriptive title for what this breakpoint is going to be used for.
  3. Add a property to the node with the Name “width” and the property Type of “Decimal”.
    1. The Value of this property is what defines the maximum screen size that will be defined by this breakpoint. This value refers to the resolution of the screen (in pixels).


The default collection of emulators should work just fine for most situations. However, there may be certain situations where other emulators might be preferred. For example, if you are demonstrating how the layout works to a Microsoft-oriented client, you may want to emulate the webpage(s) in a Surface tablet emulator instead of an iPad emulator. Although not a particularly plausible example, it does illustrate the point well. In these types of cases, follow the tutorial written by Ankur Ahlawat here to create your own emulator and add it to the responsive device group; Ahlawat also covers how to remove emulators from this group. More information about the emulators in Adobe Experience Manager can be found here.

These emulators can emulate each device in both portrait (the default) and landscape views. The orientation of the emulated device can be toggled by clicking the “Rotate” button pictured below.


Defining the Display and Control Logic of the Responsive Layout
The following examples are concerned with the clientlibs, specifically the CSS files and the LESS file. More information on this topic can be found here.

To change how the page looks, files in the /etc/designs/[new_project]/clientlibs folder are edited. This holds true as long as no other CSS files or folders are overwriting these. If changes in these files are not reflected when your page is reloaded, first clear your browser’s cache. If the problem persists, inspect your project/page to see if and/or where, and by what files, these default files are being overwritten.

We will demonstrate how each file in the folder, mentioned above, can be edited to customize how your layout behaves and looks. Note: Portions of the files have been omitted for brevity and readability.

File: /etc/designs/[new_project]/clientlibs/grid.less

This file does three important things:

  1. Defines the maximum number of columns in each grid.
    1. This should not be changed unless you are sure of what you are doing.
    2. Individual grids can be defined with a different maximum number of columns, though this is also not recommended unless you are sure what you are doing.
  2. Sets the global padding space between components in the grids.
    1. This value can be overwritten for individual grids.
    2. Height and width padding can be configured separately and independently from one another.
  3. Using media queries, this file implements the breakpoints defined earlier in this article.
    1. Even though each page in the project must have its own breakpoints, as long as they are defined the same, this file will implement them all the same way.

If this file is edited, it must be recompiled before use. The compiled file should always reside in the /etc/designs/[new_project]/clientlibs/css/generated/ folder.

To set the padding inside the grids:
Edit the following section of the file:

/* add gutter in the grid */
.aem-gridColumn {
	Padding: 0 5px;

To something similar to this example where the right and left padding is set
to 15 pixels:

/* add gutter in the grid */
.aem-gridColumn {
	Padding: 0 15px;

Note: Since these values pad both sides of the width as well as the height, half of the total desired space between components should be defined here.

To implement other breakpoints:
Append to the end of the file the following format:
1. The [max_width] variable should be the maximum width as defined by this breakpoint.
2. The [min_width] variable should always be the maximum width of the next smallest breakpoint plus one.
3. The [breakpoint_name] variable should be short, concise, and meaningful.
4. Other breakpoint definitions and implementations may need to be edited as well. Especially when these definitions begin to overlap each other.

File: /etc/designs/[new_project]/clientlibs/style.css
Defines the default CSS class definitions for the page.

File: /apps/aem-prototypes/components/clientlibs/column.css
Defines the look of the column controller, both in its unconfigured state as well as when it is in use. There are three important classes to be aware of in this file:

  • column-control-placeholder: Defines how the column controller looks when not yet configured.
  • row-border: Defines the look of the border that surrounds the controller as a whole.
  • col-border: Defines the appearance of the border surrounding each of the column controller’s individual columns.

File: /apps/[new_project]/components/clientlibs/bootstrap.min.css
Defines additional CSS classes for the column controller and its contents. Some additional information and usage examples using the Bootstrap framework can be found in this article by Jake Rocheleau.

File: /etc/designs/[new_project]/clientlibs/bootstrap.css
Defines additional CSS classes for the page and overwrites any classes in the file /etc/designs/[new_project]/clientlibs/style.css that have the same name.

Files: /etc/designs/[new_project]/clientlibs/responsive-*.css
Define additional CSS classes for the page. These definitions should always include an encapsulating media query that follows the screen widths indicated by the file name. This is important for ease of use, internal consistency, and debugging. They can also overwrite any classes in the file /etc/designs/[new_project]/clientlibs/style.css or /etc/designs/[new_project]/clientlibs/bootstrap.css that have the same name.

Using the Contents of the Optionals Folder
The optionals folder was discussed briefly in part 2 of this series. This will be a more in-depth look at what is contained within this folder and how to use this content to add additional features and/or different customizations. None of the contents of this folder are needed in order to get the basic functionality of the responsive layout system working. However, these optional versions may be used to make your project more robust, look different, or behave differently.

It should be noted early on in this discussion that the libs folder is generally not altered in the manner that will be discussed in the first two parts of this section. These alterations may not work in versions later than Adobe Experience Manager 6.1, they may become unnecessary, or the files within the optionals folder may just need to be altered in order for them to work properly.

As mentioned in Part 2, this folder contains a responsive grid component that can replace the one found at /libs/wcm/foundation/components
/responsivegrid using the CRXDE Lite interface. This replacement dialog box uses a dropdown selector instead of a text field for the “Columns” design option. This ensures that the user and/or author can only use valid inputs that won’t break the functionality of the Layouting mode, and thus it is more robust.
Screen Shot 2016-02-22 at 2.44.42 PM

The file /apps/aem-prototypes/optionals/ui.emulator.js allows the use of an emulator device group other than the responsive group. By default, this other group is called “custom”; however, this can be changed to any group name you like. If the name doesn’t match an existing group, a new group with that name should be created as described under “Breakpoints and Emulators”. Creating the new emulator definition requires replacing the file /libs/cq/gui/components/authoring/clientlibs/editor/js/ui/ui.emulator.js with the one at /apps/aem-prototypes/optionals/ui.emulator.js and changing the word “custom” within the showCurrentDeviceTooltip function to whatever group name you chose. This alteration may seem strange—because it is! The name of the current deviceGroup must be hardcoded into this tooltip, otherwise, the emulators won’t work. Hopefully, this will be fixed in a later version of AEM. The “custom” device group can be seen in use in the image below.
Screen Shot 2016-02-22 at 2.37.28 PM

By replacing the file /apps/aem-prototypes/optionals/PreviewLayer.js with the file /libs/cq/gui/components/authoring/clientlibs/editor/js/layers/PreviewLayer.js, AEM will now refresh whenever the mode is changed. This is highly recommended whenever ghost components are being (or might be) used.

This concludes our series on how to use the new responsive layout in Adobe Experience Manager 6.1; we feel that these techniques and tools will help AEM Front-end Engineers provide higher-quality responsive designs that better leverage the platform’s capabilities. Thank you for reading, and subscribe to this blog for more informative articles like this.