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.


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>
            <!-- Generate bundle header containing all configuration annotation classes -->
            <_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


Hello, I am an enthusiastic Adobe Community Advisor and a seasoned Lead AEM Developer. I am currently serving as an AEM Technical Lead at MNPDigital.ca, bringing over a decade of extensive web engineering experience and more than eight years of practical AEM experience to the table. My goal is to give back to the AEM Full Stack Development community by sharing my wealth of knowledge with others. You can connect with me on LinkedIn.

Leave a Reply

Your email address will not be published. Required fields are marked *


Back To Top