HTL caconfig Global Variable for Context-Aware Configuration in AEM

Context-Aware configuration contains a Scripting Binding Values provider with automatically registeres a caconfig variable in your HTL/Sightly scripts to directly access context-aware configurations. It supports both singleton configurations and configuration lists. Please note that configuration lists are only supported when configuration metadata is present (e.g. via an annotation class).

In this article we will step through how to use the caconfig global variable in HTL Sightly.

Quick Links

Accessing Singleton Configurations
Accessing Configuration Lists
Accessing Nested Configurations
Adding Necessary Dependencies

1. Accessing Singleton Configurations

Singleton configurations are those that you expect to have a single instance per context or configuration resource. To access a property of a singleton configuration in HTL, you can use the caconfig variable followed by the configuration’s fully qualified name. For example, if you have a configuration named x.y.z.ConfigSample, you can access its stringParam property as follows:

1
2
3
4

<dl>
<dt>stringParam:</dt>
<dd>${caconfig['x.y.z.ConfigSample'].stringParam}</dd>
</dl>

2. Accessing Configuration Lists

Configuration lists are useful when you have a series of similar configurations that you want to access as a collection. To access properties of configuration items in a list, you iterate over the configuration list using the data-sly-list attribute in HTL. For example, for a configuration list named x.y.z.ConfigSampleList, you can access the stringParam of each item as follows:

1
2
3

<ul data-sly-list.item="${caconfig['x.y.z.ConfigSampleList']}">
<li>stringParam: ${item.stringParam}</li>
</ul>

3. Accessing Nested Configurations

For nested configurations, HTL allows you to traverse the configuration hierarchy using a slash (/) as a separator. For example, to access a stringParam nested within a nestedConfig configuration, you would use:

1	${caconfig['x.y.z.ConfigSample']['nestedConfig/stringParam']}

4. Adding Necessary Dependencies

To enable the automatic registration of the caconfig variable and the scanning of configuration annotation classes, you need to include the Context-Aware Configuration bnd plugin in your project’s build configuration. This bnd plugin scans the classpath of a bundle Maven project at build time and automatically generates a Sling-ContextAware-Configuration-Classes bundle header for all annotation classes annotated with @Configuration.

Here are the configurations for the Maven Bundle Plugin and the bnd Maven Plugin:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>

<_plugin>org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin</_plugin>
</instructions>
</configuration>
<dependencies>
<dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.caconfig.bnd-plugin</artifactId>
<version>1.0.2</version>
</dependency>
</dependencies>
</plugin>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<plugin>
<groupId>biz.aQute.bnd</groupId>
<artifactId>bnd-maven-plugin</artifactId>
<configuration>
<bnd>
...
-plugin org.apache.sling.caconfig.bndplugin.ConfigurationClassScannerPlugin
</bnd>
</configuration>
<dependencies>
<dependency>
<groupId>org.apache.sling</groupId>
<artifactId>org.apache.sling.caconfig.bnd-plugin</artifactId>
<version>1.0.2</version>
</dependency>
</dependencies>
</plugin>

References: https://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration.html

HTL caconfig Global Variable for Context-Aware Configuration in AEM