Use Cases and Tips for Contextual Content Variables (CCVAR) from ACS AEM Commons

HOW DO CONTEXTUAL CONTENT VARIABLES WORK? 

The Good Ol’ Sling Rewriter 

The CCVAR tool functions via a custom Transformer for the Apache Sling Rewriter module. This module provides a pipeline that generates HTML (and XML or JSON in some cases), passes that through various transformers that may modify the content, and finally serializes that HTML. Most AEM projects use the same module to enable other neat transformer features like AEM’s Link Checker and ACS Commons' Versioned Clientlibs. The “ccvar-transformer” will parse your content and rewrite any contextual content variables that ACS Commons' PropertyAggregatorService has aggregated. 

The Content Variable Provider Interface 

How does the Property Aggregator collect contextual content variables? As mentioned above, the out-of-the-box CCVAR tool sets up contextual content variables for page properties through the AllPagePropertiesContentVariableProvider, which implements the ContentVariableProvider interface. An implementation of the ContentVariableProvider interface must provide two simple methods: 

1. The accepts method: determines whether or not the current ContentVariableProvider is relevant given the context of the request. 
2. The addProperties method: adds the content variables to the passed map via the PropertyAggregatorUtil. When added to this map, the caller defines the prefix and property name of the variables. 

The Transform Action 

Beyond the two key players already listed, the TransformAction service interface allows developers to enable actions on the content variables. This feature could allow an author to change text casing or include a specific format for a date. Another simple implementation of two methods: 

1. The getName method: defines the name of the action that the authors will reference. (ie. !uppercase). 
2. The execute method: will handle the actual processing of the value. 

WHERE COULD I USE CONTEXTUAL CONTENT VARIABLES? 

I have faced several different use cases across various AEM projects that have required custom solutions similar to what ACS Commons provides through Contextual Content Variables. Typically, these use cases eliminate monotonous tasks or allow more flexible authoring experiences. CCVAR is an elegant, easily extensible approach to tackling these general use cases and likely others. 

Reusable or Templated Content 

Whether it’s an Experience Fragment or an Editable Template within AEM, we want our content created for reuse across various products, campaigns, profiles, etc. Yet, we want the content to be more relevant to the specific scenario. 

Without CCVAR, to make these experiences distinctive, we could take one of these paths: 

1. An author could create multiple variations of the Experience Fragment or manually author relevant data for every page using the template—another thing for authors to maintain. 
2. A developer must create a custom component (or a custom Sling Rewriter) for this experience to populate data—another thing developers must maintain.
   
   

With CCVAR, authors may create templates or experience fragments using simple components authored with contextual content that CCVAR populates. This approach doesn’t require authors to maintain content throughout multiple instances individually, nor does it require specific implementations or custom components from developers that pull in that content. 

Semi-dynamic data 

Certain content may require continuous authored updates – the latest application or registration dates for an event or program, the current rate of interest or fees, etc. Any bit of data that pops up in numerous places throughout the site might benefit from CCVARs. Often, these tasks are tedious and, unless intentionally scheduled, are handled in a rush to remain compliant with some standard or regulation. 

Note: Highly dynamic data may require a frontend or different solution that simplifies caching complexities. See more below about caching considerations. 

Probably more! 

The CCVAR tooling is a relatively new addition to ACS Commons, and I have only seen a handful of uses thus far. Still, certainly, this will be a good baseline approach to populating content in many various contexts. 

TIPS & CONSIDERATIONS 

Author Enablement 

One of the most appealing aspects of this tool is that an author can wield the power of CCVAR to create content with more contextual and dynamic information. But to wield that power, the author needs to be trained to use CCVARs. They need to know how the syntax works, what variables exist, and where they may be used. Without this, your CCVARs will remain hidden knowledge that no one seems to be using! 

CCVARs can be a bit abstract until demonstrated to an author in the specific contexts where they are relevant to the author. Even once the abstract is made more concrete, it can often be difficult for an author to remember what prefixes and property values the developer enabled. The go-to and necessary solutions for these are author training and documentation. Any minor (or big) steps towards making this knowledge visible and grok-able are worth taking. 

Cache Good Not Bad 

One great benefit of utilizing CCVAR is that the dispatcher can cache this dynamic or contextual content as part of the page. The content doesn’t need to be repopulated by the front-end of your site or re-evaluated for every request. With some use cases, there will need to be some strategy to ensure that the cached content is not stale and invalidated when required. 

One relatively simple solution for this is to implement a Scheduler that executes on the appropriate timetable and invalidates the cache for any page using the Content Variable Provider. Other use cases may call for different solutions, but always ensure that the caching strategy is defined. 

Providers and Performance 

As mentioned above, CCVAR operates server-side and can be cached along with the pages of your site, relieving the future load on the environment. But that doesn’t mean the performant cost of your providers is a moot point. Rewriting is not a free process, and ContentVariableProviders should be formulated to avoid costly logic and executed only when needed. 

The ContentVariableProvider’s accepts method is the most straightforward place to ensure logic runs only when needed. Use the passed request object to check for a specific page path or template type or check for a flag in the page properties that explicitly enables that particular provider. 

Typically, when the CCVAR tool is enabled, a site’s existing Sling Rewriter configuration will be updated to include the ccvar-transformer. The Apache Sling Rewriter module only resolves a single rewrite configuration for any given request, and this single configuration should be sufficient for most cases. However, if the CCVAR tool is only needed in a specific area of the site, add a new Sling Rewriter config with a higher priority order value and a more specific path value. 

Default Values and Placeholders 

When an author tries to use a contextual content variable and that value is not added to the Property Aggregator map, the page will render with the CCVAR without rewriting it (ex. ((page_properties.pageTitle))). Some backend issues or missing context may cause this value to remain unpopulated. Most developers would take one look at these parentheticals and cringe - they're unrefined and ugly. A default value could be passed into the map when services fail to provide the information; however, choose your fallback carefully.  An empty string may disguise the issue but lead to grammatical or visual problems. And perhaps, making the issue apparent will help your team identify and fix the problem more quickly! Think about the possibility of a data issue and whether or not there is something more seemly and helpful to display in those cases. 

SUMMARY 

In Contextual Content Variables, ACS AEM Commons provides another incredible open-source tool for the community that fills a relatively common use case with an extensible solution. It can make your content less dumb and your authoring less tedious. I think many will find that the tool proves to be useful for many projects and a variety of use cases.