Shared Component Properties

Tags:

December 2, 2016 | Brett Birschbach

This feature extends the out-of-the-box (OOTB) component authoring capabilities of Adobe Experience Manager (AEM) to include fields that can be configured once per website rather than on every single instance of a given component. Added fields come in two flavors, shared properties that apply to all instances of a given component type, and global properties that span all components within a website. Shared Component Properties is the only tool in AEM that generically addresses the challenge of granular, shared properties within a component in a way that functions “natively” for both authors and developers.

Use Cases

Once a team starts leveraging Shared Component Properties (SCP), all sorts of use cases become apparent. It can be argued that this feature belongs as a core feature of the AEM platform.

Use cases for which we’ve found SCP particularly useful include:

  • Authoring component labels such as “Share this page” or “Add to Favorites” that are used on hundreds of site pages
  • Enabling default “read more” link text while also allowing local overrides
  • Replacing all instances of hard-coded strings in the code (e.g. button labels), eliminating the need for a translation library in AEM
  • Ensuring all instances of a component show the same content on a single site, but different across sites in a multi-site solution
  • Configuring site header and footer without an inherited parsys (iparsys)

How to Use

1. Enable the Shared Component Properties OSGi Service

Enable back end support for SCP via a blank OSGi configuration of the `com.adobe.acs.commons.wcm.properties.shared.impl.SharedComponentPropertiesImpl` service, which you can deploy from your codebase as an empty `sling:OsgiConfig` node.

screen shot of Shared Component Props Enable Osgi

2. Enable the Shared Component Properties Authoring clientlib

Enable front end support for SCP by creating an empty client library in AEM within the `cq.authoring.editor` category that embeds `acs-commons.shared-component-properties` and includes an empty `js.txt` file.

screen shot of Shared Components Props ClientLib

3. Configure a Page Root Provider

Configure the ACS AEM Commons service for Page Root Provider, which allows AEM to keep SCP contextual to your website. This is done by adding an OSGi factory config for `com.adobe.acs.commons.wcm.impl.PageRootProviderConfig`. You can do this from the admin console in AEM, or using a config file from your codebase similar to step 1.

screen shot of Shared Component Props Page Root Provider

4. Add the Page Info Provider to Your Page Component

Add the SCP Page Info Provider `com.adobe.acs.commons.wcm.properties.shared.impl.SharedComponentPropertiesPageInfoProvider` to your base page component so that the authoring interface knows for which components to display icons to modify shared and/or global properties.

screen shot of shared components props clientlib

Tip: If you find the authoring interface is no longer working correctly after adding the SCP Page Info Provider, it could be that other `cq:infoProviders` are no longer inheriting from page supertypes. It’s a bug we’ve run into, and in that case, you can work around it by specifying all providers directly on your base page type.

screen shot of Shared Components Props Page Info Provider Rext

5. Add a Shared And/Or Global Dialog to Your Component

Having now enabled SCP in your AEM instance, add shared and/or global properties to your component by adding `dialogshared` and/or `dialogglobal` nodes to your component that are in every way similar to the standard `cq:dialog` node.

Example Dialog for Shared Properties:

screen shot of Shared Component Props Dialog Shared

Example Dialog for Global Properties:

screen shot of Shared Component Props Dialog Global

These dialogs will be accessible to authors via icons in the standard authoring interface that they are already accustomed to.

screen shot of Shared Components Props Icons

In addition, you can choose to include standard, instance-level properties via the usual `cq:dialog` node. A standard property is considered an override of a shared or global property when it shares the same `name`, allowing authors full flexibility of when to display a shared value versus a custom value.

screen shot of Shared Component Props Dialog

6. (Recommended) Inject Shared/Global Properties Into Your Component Sling Model

To access the values of shared and global properties for rendering the component, inject the properties into your component’s sling model using the `@SharedValueMapValue` injector from ACS AEM Commons, which is analogous to the `@ValueMapValue` injector from sling for standard properties.

screen shot of Shared Component Props Sling Model

Note that when injecting a property, values set at the instance level will automatically override those set at the shared or global levels.

7. Render Shared/Global Properties From Your Component HTL (Sightly) Code

Assuming you are using a sling model, render the shared and global properties into your HTML no different than standard properties. The fact that some properties are shared or global is abstracted away from the front end by the automatic injection in the sling model.

screen shot of Shared Component Props HTL With Model

If you’re not using a sling model, however, don’t fret. You can still render shared and global properties directly from your HTL (or even JSP) code by accessing the `mergedProperties` map provided automatically by SCP.

screen shot of Shared Component Props HTL Without Model

Learn More

For a more extensive overview of the SCP, the story of how it came to be, and the use case behind the code example here, check out our original blog post on Shared Component Properties. You can also visit the official documentation for additional implementation guidance including troubleshooting.