Improving Context-Aware Configuration Strategies in AEM

Context-aware configurations are a powerful feature of Sling that links specific configurations to a content resource or resource tree, representing a website or a tenant site.

Sling is an open-source Java framework that improves the efficiency of AEM content delivery and management. Context-aware configurations are helpful for multi-brand, multilingual, or regional sites. They allow you to isolate business configurations per tenant, making AEM implementations more flexible and scalable.

If you're new to this feature and want to learn more about it and how it works, read our previous blog post, Context-Aware Configurations in AEM.

The traditional method of using context-aware configurations presents several challenges, such as a need for authoring capabilities and a human error-prone manual configuration process. To address this, WCM.io introduced additional features to make managing and configuring context-aware configurations easier. This post will explore the limitations of the default Context-aware configurations and how the WCM.io framework can address these concerns:

• Using the Context-Aware Configuration Editor

• Using the Context-Aware Extensions

• Leveraging the Reference Provider

Limitations of Sling Context-Aware Configurations

There are some limitations or at least things to keep in mind when planning to use Sling context-aware configurations in a large and modern AEM implementation.

Lack of Author Capabilities

In most cases, the configurations used in Sling context-aware setups are driven by business needs. For example, in our previous post, we discussed email as one potential use case for these configurations. Therefore, authors should have a user interface that allows direct interaction with these configurations rather than relying on developers for updates.

Setting the Context Path

The default method for setting the context path to a subtree uses the sling:configRef property. This is usually a manual process that requires knowledge of the content tree and the configuration path from which the context-aware settings will be applied. This approach is manageable when dealing with a small amount of content or configurations. However, as the content scales and you incorporate context-aware configurations across multiple languages, brands, or regions, this process becomes tedious and error-prone.

Publishing the Configurations

By default, configurations are stored under /conf, which isn’t the most user-friendly path for publication. This often requires developer involvement to ensure configurations are correctly moved to the appropriate locations. This reliance on the development team can create unnecessary dependencies and complicate the publishing process.

The Struggles of Unit Testing Context-Aware Configurations

Standard testing methods often didn’t work well because they couldn’t handle how these configurations change based on different situations. To test them properly, you needed more advanced methods, like creating detailed mock environments or using special frameworks.

The WCM.io Project

WCM.io is an open-source project that provides libraries and extensions for AEM-based applications. Of particular interest are a couple of libraries explicitly built to address some of the limitations described above, which are part of the default settings in a Sling context-aware implementation.

Context-Aware Configurations Editor

The Context-Aware Configuration Editor Template for AEM empowers AEM authors by providing an intuitive interface for managing configuration data tied to their current context pages. This feature addresses the challenge of limited authoring capabilities. It supports a wide range of features, including managing singleton configurations, configuration collections, and nested configurations while displaying essential metadata and default values. The editor accommodates various data types and arrays, controls the inheritance of collections and properties, and allows for overridden values. Moreover, authors can define custom widgets for specific configuration properties, such as path browsers, etc.

To include the Editor as part of your project, you can add the necessary dependencies and embed them as part of your filevault-package-maven-plugin

<!-- Embeding the io.wcm CAConfig Editor in the Plugin section  -->
<embedded>
	<groupId>io.wcm</groupId>
	<artifactId>io.wcm.caconfig.editor</artifactId>
	<target>/apps/estebanSite-vendor-packages/application/install</target>
</embedded>
...
<!-- Adding the io.wcm CAConfig Editor Dependency -->
<dependency>
	<groupId>io.wcm</groupId>
	<artifactId>io.wcm.caconfig.editor</artifactId>
	<version>${io.wcm.caconfig.version}</version>
</dependency>

Context-Aware Extensions for AEM

We will focus on three(3) of these extensions, which will help to overcome the limitations mentioned in the previous section.

Context Path Strategies

This extension offers powerful alternatives that streamline the management of context-aware configurations in AEM. It eliminates the tedious requirement of setting @sling:configRef properties, allowing contexts to be defined and managed more efficiently.

It provides two key strategies: Absolute Parents and Root Templates. The Absolute Parents strategy allows users to specify absolute parent levels as context roots while employing whitelists and blacklists to control which paths are accepted. This simplifies the configuration process and ensures that changes in content structure are handled gracefully. Meanwhile, the Root Templates strategy enables context detection by matching parent pages against a defined list of templates, allowing more flexibility in managing valid context paths.

Both strategies can be set up via OSGi configurations, and the official documentation offers detailed examples to guide users through the configuration process. Depending on specific requirements, you may choose one strategy over the other. However, in most scenarios, the Absolute Parents strategy is often sufficient for effectively managing context-aware settings.

Similar to the Editor, you need to add necessary dependencies and embed them as part of your filevault-package-maven-plugin

<!-- Embedding the io.wcm Extensions in the Plugin Section -->
<embedded>
	<groupId>io.wcm</groupId>
	<artifactId>io.wcm.caconfig.extensions</artifactId>
	<target>/apps/estebanSite-vendor-packages/application/install</target>
</embedded>
...
<!-- Adding the io.wcm Extensions in the Dependencies Section -->
<dependency>
	<groupId>io.wcm</groupId>
	<artifactId>io.wcm.caconfig.extensions</artifactId>
	<version>${io.wcm.caconfig.extensions.version}</version>
</dependency>

Persistence Strategies

Sling context-aware configurations usually save settings in nodes under /conf, which complicates tasks like AEM content replication. A better approach is to use cq:Page nodes for storing configurations, similar to the AEM ConfMgr. While there is support for reading from these nodes, writing to them has been limited in the past.

This Extension offers improved options for managing configurations. The AEM Page persistence strategy allows you to store and update configurations within /conf using cq:Page nodes. Another option, the Tools Config Page, works alongside context path strategies to read and save configurations at specific locations, like /content/{context}/tools/config/jcr:content. This setup simplifies the management of configurations and allows authors to replicate changes to live instances by easily activating the relevant pages.

Reference Provider

In a nutshell, this extension creates a direct relationship between published pages and their corresponding context-aware configurations. This ensures that the associated configurations are seamlessly activated when a regular page is activated or published. However, it's essential to note that this functionality only works if the configurations are stored within a page, specifically using the AEM Page persistence strategy mentioned earlier.

Mock Helper

While it may seem trivial, the Mock Helper is a valuable addition, especially when using the extensions mentioned above. This framework allows you to set up a testing environment that can effectively mock the context-aware configurations a resource should utilize. It also supports configurations made through the previously discussed extensions.

Using the Mock Helper is simple, and the documentation offers clear guidance. I'll include some snippets here for quick reference to help streamline your setup.

import org.apache.sling.caconfig.ConfigurationBuilder;
import io.wcm.testing.mock.wcmio.caconfig.MockCAConfig;
import static org.apache.sling.testing.mock.caconfig.ContextPlugins.CACONFIG;

// 1. Create the AEMContext using CAConfig plugin
private final AemContext context = new AemContextBuilder().plugin(CACONFIG).build();

// 2. Set up the Context-Path
final Page page = this.context.create().page("/content/estebanSite/us/en/blog1");
// Depending on the strategy you use
MockCAConfig.contextPathStrategyAbsoluteParent(this.context, 2, 3);
// MockCAConfig.contextPathStrategyRootTemplate(this.context, templatePaths);

// 3. Mock the config values. MyCAConfig.class only has a "country" property
Map<String, Object> properties = Map.of("country", "United States");
MockContextAwareConfig.writeConfiguration(this.context, page.getPath(), MyCAConfig.class, properties);

// 4. Verify as needed. You could directly check if the config works like this:
DemoCAConfig myConfig = page.adaptTo(ConfigurationBuilder.class).as(DemoCAConfig.class);
assertNotNull(myConfig);
assertEquals(myConfig.country(), "United States");

Wrap up

Sling context-aware configurations are a fantastic feature for multi-brand, multilingual, or regional AEM implementations, but there's always room for improvement. By highlighting where the default setup could be improved, we can tap into the power of the WCM.io framework to make Sling context-aware configurations even better and take your implementation to the next level.

If you’re looking for help getting more out of your AEM implementation using context-aware configurations (or any other feature), we can help. Oshyn is an Adobe partner that can help with everything from migration and implementation to continuous maintenance and content operations.

See if your current AEM implementation was done correctly by checking our Adobe Experience Manager Implementation Best Practices ebook.