Context Aware Configurations in AEM

Often times when we want to have a configuration available on multiple locations throughout the content tree, we reside to extending our page properties with new tabs and configuration options. This leads to a clutter in your page props, where it becomes painful to work with very easily. This is one of the reasons to start using context-aware configurations.

Introducing context aware configurations

Context aware configurations allow you to set configurations that will apply to your whole content tree. When wanted, the inheritance can be broken at any level to stop it from being applied or to change the configuration from that point onwards. In AEM, you need to create a configuration page (which is based on a template wcm.io provides) where you can add multiple configurations for your components. This makes it so you have one page with a full overview of all your configurations where you can easily add, change, and delete them.

Example
Let’s say we are in an e–commerce environment for a clothing store with the following content tree:

/content
    /clothing-store
        /t-shirts
        /pants
        /sweaters
        /jackets

The store has created a new promotion component which consists of an image and some text with information about the promotion. It will be added to all product detail pages throughout the whole website. The component should be the same for T-shirts and sweaters but needs to be different for pants. For jackets, it cannot be there at all since there are no promotions currently active. In a normal scenario this becomes difficult to manage. You could consider creating an experience fragment with different variations, but you would then have to manually add the correct variation to the product pages or write code to dynamically pick the right variation based on the path in AEM. This is where context aware configurations come in.

First off, the component will not read the configuration from its dialog like we are used to, but from the context aware configuration. This makes it so we can add the component to the template and fill it dynamically based on the configuration. There’s no need to add the component on individual pages, making it less work for content authors. As for the configuration, we should start by creating a configuration at /content/clothing-store. This configuration will be applied to all promotion components under this path. Because T-shirts and sweaters should have the same configuration, we will use the image and text for those promotions.

Pants need a different configuration, so we will now create a new configuration at /content/clothing-store/pants. When adding this, you will see that inheritance is enabled and the values from the upper level are already filled in.

We can disable the inheritance and change the values, which will now be applied to all promotion components under this level.

For jackets, we will also create a configuration page, but here we will delete the configuration for the promotion component or make the values empty based on how you’ve set it up. In our overview, we will now not see the configuration anymore.

Let’s compare it with the configurations for pants:

Let’s compare the pages!

Collections

Collections allow you to have multiple configurations for a single component. They are comparable to a multifield from the regular configuration dialog. This does mean that the component needs to have some logic that determines which is the correct configuration to choose from. You could select a configuration based on one of the configured values, or you could pick a random one if that’s what you need.

Let’s go back to our e-commerce store to give you an example. We want to have a custom component that shows a description and some additional information about the material the T-shirt is made of. Every page under /content/clothing-store/t-shirts has a tag configured, like “cotton” or “polyester”. We can now add 2 configurations in which we will select the corresponding tag “cotton” or “polyester”, along with the descriptions and information we would like to show for this material. When adding the component to a t-shirt page it should check if the configured tag is also applied to the page itself. If so, we know which configuration to use for our component.

Context path

A context aware configuration needs to know in which context it should work. This context will always be visible right at the top of your configuration page. As I mentioned before, the configurations will apply to the whole content tree, but it still needs to know where to start from and how to handle underlaying levels. This can be done by setting a context path.

There’s two ways to set a context path:

Add a @sling:configRef property to each root page for a context’s subtree. This allows you to manually set a context path for all the pages individually.
Use the sling context aware configuration extensions provided by wcm.io

For most cases in AEM, the second option is the way to go. Wcm.io provides an extensions bundle that is specifically designed for AEM usage and spares you lots of work to individually set context paths to your pages. They also allow you to choose between some different ways of setting the path to match your project’s structure in the best way possible.

The technicals

In AEM, there are two ways to integrate context aware configurations into your project. You can either add a dependency in your POM file, or you can download a package and upload it through your CRX instance.

After installation, you will need to create a new template. You should use the specific resource type that is included in the bundle.

        <?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0" jcr:primaryType="cq:Page">
    <jcr:content cq:lastModified="{Date}2020-07-12T16:13:25.676-07:00" cq:lastModifiedBy="admin" cq:template="/conf/wknd/settings/wcm/templates/caconfig-page-template" jcr:primaryType="cq:PageContent" sling:resourceType="wcm-io/caconfig/editor/components/page/editor">
    </jcr:content>
</jcr:root>

Note that in most projects, you will still need to allow the newly created template in your root pages before you can add it as a page.

Once you have your template, you can start adding your configuration dialogs using an annotation class.

@Configuration(label = "My custom component", description = "Site-wide configuration for our custom component")
public @interface MyComponentConfig {

    @Property(label = "Text to display", description = "Enter the text that you want to display")
    String text();

    @Property(label = "Color", description = "Select the color", property = {
            "widgetType=dropdown",
            "dropdownOptions=["
                    + "{'value':'red','description':'Red'},"
                    + "{'value':'green','description':'Green'}"
                    + "]"
    })
    String color() default "red";

}

If you would like to work with a collection, simply add “collection = true” to the @Configuration annotation. You can see that some custom widgets can be used, which you can find here: https://wcm.io/caconfig/editor/usage.html

At this point you can add a page using your new template in your AEM site structure and configure your newly created configuration. There are multiple ways to use your configured values in your HTL files. One way is to use them directly is HTL like this:

</p>
<p>${caconfig['com.custom.core.siteconfig.MyComponentConfig'].text}</p>
<p>

Alternatively, you can create a sling model that adapts the incoming resource to your custom configuration class:

private MyComponentConfig config;

@PostConstruct
public void init() {
    config = resource.adaptTo(ConfigurationBuilder.class).as(MyComponentConfig.class);
}

If you are working with collections, you will need to select the correct config based on one of the values. It could end up looking like this:

private Collection<MyComponentConfig> configs;

@PostConstruct
protected void init() {
    this.configs= resource.adaptTo(ConfigurationBuilder.class).asCollection(MyComponentConfig.class);
}

public List<String> getTexts() {
    return this.configs.stream().map(MyComponentConfig::text).collect(Collectors.toList());
}

To finish off, you will need to set up the context path strategy. Depending on how you want to use context aware configurations, this can change quite a lot from project to project. There is a good guide online that goes through the options you can set and what they mean, so I will not go into detail about that too much in this blog. You can find that guide here: https://wcm.io/caconfig/extensions/context-path-strategies.html

Adding your configuration to one level only

There are cases where you might want to add a configuration only on one level, for example on country level. You could choose to add something to the country page properties, or you can do some custom workarounds in context aware configurations.

The configuration editor bundle which you installed before comes with a class called ConfigurationEditorFilter. This class is used when you edit one of the configurations that matches with the context path pattern regex, which you have configured in the extensions OSGI config. If there’s a match, the “allowAdd” method is called. This method checks which context aware configurations can be added to this location of the content tree. If you override this method in a custom Java file, you can customize this to your liking. Here’s an example:

@Component(service = ConfigurationEditorFilter.class, immediate = true, property = {

ContextAwareService.PROPERTY_CONTEXT_PATH_PATTERN + "=^/content/wknd(/language-masters)?/([a-z]{2})/country-config/jcr:content$"
})

public class CountryConfigurationEditorFilter implements ConfigurationEditorFilter {

    @Override
    public boolean allowAdd(@NotNull final String s) {
        return "com.wknd.aem.core.configurations.country.PaymentOptionsConfiguration".equals(s);
    }
}

Our services

Spotlight

Our solutions