Explore Expression Customizer in Adobe Experience Manager

Ankur Ahlawat
Aug 26, 2019 · 5 min read

Expression Customizer is an extension of Expression Language and available since AEM 6.3, but I have seen very few developers making use of it. In nearly every AEM Sites project, we come across a scenario where we need to update component dialog field values based on selection in design dialog. Expression Customizer can help with this.

An example could be hiding a title field in dialog if we select the “hide title” checkbox in the design dialog. In order to implement this requirement, usually developers write custom JavaScript/jquery in client libraries and add the cq.authoring.dialog client library category to it to trigger JS when content authors open dialog. But writing this JavaScript code is a time-consuming process and wastes lot of productive time, because dialogs are getting more complex by the day.

Expression Customizer provides implicit cqDesign objects, which developers can directly use inside dialog field properties and update dialog visibility/behavior dynamically based on design dialog selection.

Lets see more about it in detail. This tutorial will cover:

  • Overview (What Expression Customizer is.)
  • How to use Expression Customizer.
  • Which use cases can be solved using Expression Customizer.
  • The limitations of Expression Customizer.


Due to increasing complexity of component dialogs to have numerous options for content authors, it’s becoming very difficult to keep the user interface simple, even though the user might require only a fraction of options at particular moment. By using Expression Customizer to hide options based on conditions, we can make content authors’ lives very simple by hiding unnecessary options. Content authors, template authors, or admin users can enable or disable options from the design dialog at any point of time. Below is a snippet of how cqDesign implicit object is created.

Design design = getDesign(); 
ExpressionCustomizer customizer = ExpressionCustomizer.from(request); customizer.setVariable("cqDesign", design);

How to use Expression Customizer

Using cqDesign Object is very simple. A developer can go to the dialog field and add (e.g. cqDesign.myProperty) a node property to access design dialog property values. Expression Customizer is used throughout core components in AEM. Lets explore a few of the most commonly used scenarios.

Examples of Expression Customizer

Lets look at an example using the Teaser core component.

1. Hiding fields based on Design Dialog Selection:

By default, content/page authors has the option to add Title and Description for the Teaser component. Lets see how the core component team is hiding and showing this field.

teaser dialog

In the design dialog of the Teaser component, authors can select an option to hide title and hide description. Go ahead and select these checkboxes next to them and click on save.

A policy node is created under /conf/we-retail/settings/wcm/policies/weretail/components/content/teaser with a property titleHidden and descriptionHidden set to true.

The hide condition is defined as the value of a granite:hide property on the dialog property node:


Title and Description option is not longer visible on dialog.
This five-minute activity saved 4-5 hours of development effort.

2. Fetch value from design dialog and populate in dialog field:

In this example we will see how to fetch design dialog values from policy node and populate it on dialog property. This is useful when you have a requirement to populate some default text that can also be authorable using design dialog, and if content authors want, they can change it on specific page.

To understand this, lets try an example with the Teaser core component. In order to fetch the description of the template you can use:


If we want to fetch a value from the design dialog, assuming we have a property by name description in the design dialog, we can use the below expression language.

fetch design dialog values

You can also write complex expression language and make use of cqDesign object for specific requirements. A few examples are listed below:-\

${cqDesign.myProperty == 'someText'}
${cqDesign.myProperty != 'someText'}
${cqDesign.myProperty == true}
${cqDesign.myProperty == true}
${cqDesign.property1 == 'someText' || cqDesign.property2 != 1 || header.myHeader} ${not empty cqDesign.myProperty ? cqDesign.myProperty : false}

Limitations of Expression Customizer (cqDesign)

  • Hiding a resource based on an expression does not replace ACL permissions. Content remains editable but is simply not displayed. To be more specific for example if a component is interacting with server for some data and population the field, the interaction will still happen only the field is hidden.
  • All out of the box properties doesn’t honor cqDesign. What i mean to say is that for example for a checkbox(granite/ui/components/coral/foundation/form/checkbox) checked property is supported but text property might not be supported using cqDesign object.

For more information visit: Expression Customizer Docs

I’m a AEM 6 Certified Lead Developer with 7+ years of industry experience and am an active member of the AEM community. Want to work together to help the AEM community? I’d love to hear from you. Just drop a mail at [email protected]

Originally published at http://www.aemcq5tutorials.com on August 26, 2019.

Adobe Tech Blog

News, updates, and thoughts related to Adobe, developers, and technology.

Ankur Ahlawat

Written by

I’m working as Technical Consultant with Adobe and AEM 6 Certified Lead Developer with 7+ years of industry experience.

Adobe Tech Blog

News, updates, and thoughts related to Adobe, developers, and technology.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade