CMS, Java

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 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 binded 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 in 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);
    • 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:
      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")));
    • REFERENCE_NAME – It can be a display-name or title for the reference.
    • REFERENCE_RESOURCE_OBJECT – Referenced content’s resource object.
    • 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

About The Author