Reference provider for AEM content

Introduction:

Reference Provider is an AEM API which provides us with a method to find all references to a particular resource. In AEM there exists a various type of reference providers which are useful for fetching all kinds of references to a specific resource.

A web page developed using AEM makes use of various kinds of content like images, content fragments, experience fragments or external data like PIM. So all of these content can have a specific Reference Provider for them which links them to a specific resource like a web page. The list of all reference providers available in AEM can be seen in the below screenshot.  From the shown list, PIMReferenceProvider is an example of a custom reference provider and rest all are already available in AEM. 

Fig-1: Reference Providers in AEM

Creating a Custom ReferenceProvider:

For creating a custom reference provider which will get us all referenced content in a particular web page we can follow these steps:

1.    Create a service class implementing com.day.cq.wcm.api.reference.ReferenceProvider interface. By doing this our custom reference provider gets dynamically bound along with other types of reference providers (for eg.- AssetReference, FragmentReference) to AEM Reference Provider.

2.    Override the method – public List<Reference> findReferences(Resource resource);
In this method, we need to write our backend logic to fetch the referenced content (for eg.- PIM Data) which is being used on the web page and then return the list of com.day.cq.wcm.api.reference.Reference class object for each referenced content.

3.    Create a Reference object for each referenced content as shown in below code segment:

Reference reference = new Reference("REFERENCE_TYPE_NAME",

"REFERENCE_NAME",

REFERENCE_RESOURCE_OBJECT,

REFERENCE_LAST_MODIFIED_TIME_IN_MILLIS);

o   REFERENCE_TYPE_NAME – It’s a reference type identifier used by AEM to put all references under a specific group and all available types are declared inside: /libs/cq/gui/components/siteadmin/admin/publishwizard/references/references.jsp. AEM already has a reference type for PIM data as “products” and we can also add more reference types in the same file as shown below:

o    

JSONObject types = new JSONObject();

types.put("asset", xssAPI.encodeForJSString(i18n.get("All Assets")));

types.put("experience", xssAPI.encodeForJSString(i18n.get("All Experiences")));

types.put("product", xssAPI.encodeForJSString(i18n.get("All Products")));

types.put("contentfragmentmodel", xssAPI.encodeForJSString(i18n.get("All Content Fragment Models")));

o   REFERENCE_NAME – It can be a display-name or title for the reference.

o   REFERENCE_RESOURCE_OBJECT – Referenced content’s resource object.

o   REFERENCE_LAST_MODIFIED_TIME_IN_MILLIS – The value stored as jcr:lastModified property of the referenced content resource.

4.    Sample code for Implementation of Reference Provider for PIM Data:

@Component(immediate = true, enabled = true, service = ReferenceProvider.class)

public class PIMReferenceProvider implements ReferenceProvider {

         /**

          * Finds references for a given resource.

          */

         @Override

         public List<Reference> findReferences(Resource resource) {

                  List<Reference> pimReferenceList = new ArrayList<>(); // an empty list to be populated with all Referenced Content

                  ...

                /**

                 * Logic for retrieving referenced PIM resource and creation of reference object for the same,

                 * and adding each reference object to the pimReferenceList.

                 */

                ...

                  return pimReferenceList;

         }

} 

Usage of ReferenceProvider in AEM:
One of the usages of ReferenceProvider in AEM is publishing all the referenced content while activating the web page.

·       All the referenced content retrieved for the web page can be seen on AEM UI by clicking on Publish Page option from page options dropdown as shown below:

Fig-2: Page Options in AEM

·       On clicking Publish Page option publishpagewizard window will open, which makes a call to ActivationReferenceSearchServlet, this servlet iterates through all the reference providers present and calls findReferences(pageContentResource) method for each reference provider and returns a unique list of references through the response which can be seen in AEM along with our custom PIM Data reference as shown in Fig-3 below:

Fig-3: References List in AEM

Source: https://labs.tadigital.com/index.php/2019/09/12/reference-provider-in-aem/