Design Dialog in AEM

A Design Dialog in AEM (cq:design_dialog) is a specialized type of dialog that plays a crucial role in managing the global or template-level configuration of components, as opposed to the instance-specific configuration handled by a regular dialog (cq:dialog).

Here's a deeper dive into understanding Design Dialogs:

1. Purpose: Global/Template-Level Configuration

• Shared Properties: Imagine you have a "Hero" component used across many pages on your website. This component might have a background color. If you want all "Hero" components created from a specific template to have a default blue background, you wouldn't want authors to set that for every single instance on every page. This is where a design dialog comes in.

• Design and Layout: Design dialogs are primarily used to define properties related to the design, layout, and general behavior of a component that should be consistent across all pages using a particular template. This promotes a consistent look and feel for your website and reduces redundant configuration by authors.

• Examples: Common uses include:

  • Setting default background colors or images for a component.

  • Defining the allowed child components within a paragraph system.

  • Configuring responsive breakpoints or column layouts.

  • Specifying options for image cropping or component styling.

2. How it Differs from a Regular Dialog (cq:dialog)

The core difference lies in where the configured data is stored and its scope:

Feature	Regular Dialog (cq:dialog)	Design Dialog (cq:design_dialog)
Scope	Page-specific / Component Instance-specific	Template-level / Global
Data Storage	Stored under the component's node within the page's JCR path (e.g., /content/my-site/en/my-page/jcr:content/my-component). This means each instance of the component on a page can have unique settings.	Stored under the /etc/designs (for static templates) or within the Template Policy (for editable templates) path (e.g., /etc/designs/my-site/jcr:content/my-template/my-component). The data applies to all instances of the component on pages created from that template.
Accessibility	Accessed when an author edits a component on a page (in Edit mode).	Accessed when an author is in Design Mode on a page or when configuring Template Policies.
Node Name	cq:dialog (Touch UI) or dialog (Classic UI)	cq:design_dialog (Touch UI) or design_dialog (Classic UI)
Reading Values	Accessed in HTL/JSP using the properties object.	Accessed in HTL/JSP using the currentStyle object (for static templates) or via cqDesign implicit variable in Sling Models (for policies).

3. Creation and Structure

• A design dialog is created as a child node named cq:design_dialog (for Touch UI) or design_dialog (for Classic UI) directly under your component's definition node (e.g., /apps/my-project/components/content/my-component/cq:design_dialog).

• The internal structure of a design dialog is very similar to a regular dialog, using Granite UI components (for Touch UI) to define fields like text fields, dropdowns, etc.

4. Authoring and Usage

• Static Templates: For older, static templates, authors would typically switch to "Design Mode" on a page. Then, by clicking on the wrench icon (design icon) for a specific component within a paragraph system, the component's design dialog would open. Any configurations made here would be saved to /etc/designs and apply to all pages using that template.

• Editable Templates and Policies: With modern AEM and editable templates, design dialog functionality is largely integrated into Template Policies. Instead of a separate "Design Mode" directly on the page, the design configurations are made when defining the component policies within the template editor. This is a more structured and governed approach.

  • When you configure a component's policy in an editable template, you're essentially configuring its cq:design_dialog properties for that specific policy. This data is stored under the template's policy node, which then applies to all pages created from that template.

5. When to Use a Design Dialog

You should consider using a design dialog when:

• You need to set default values or configurations for a component that should be inherited by all instances of that component on pages using a specific template.

• You want to provide authors with options to control the look and feel or structural behavior of a component at a higher level (template or global).

• You need to define allowed components within a paragraph system or a container component.

• You want to enable a separation of concerns, where content is managed by cq:dialog and design/layout by cq:design_dialog.

By effectively utilizing design dialogs, AEM developers can create robust and flexible components that empower content authors to build and manage web experiences efficiently while maintaining brand consistency and overall site design.