Debugging AEM Components with the AEM SDK

When working with AEM, there are times when you need to debug or customize an out-of-the-box component. Whether you’re trying to resolve an issue or simply overlay a component. Understanding how the original component works is essential. One of the most effective ways to do this is by changing the relevant components below the /libs node.

It’s important to note that there are differences between AEM on-premise and AEMaaCS. The AEM SDK for AEMaaCS behaves differently, particularly due to the use of precompiled scripts.

Scenario: Overlaying the References Sidebar in AEM’s Site Overview

Imagine you need to overlay the References Sidebar in the AEM Sites Overview. The first step is to locate the renderer responsible for generating this UI element.

Inspecting the sidebar with browser tools might show something like this:

data-foundation-layout-panel-rail-panel-src="/mnt/overlay/wcm/core/content/sites/jcr:content/rails/references/items/references.html"

This path reveals that the renderer is located under /mnt/overlay, indicating that it is indeed part of the mountpoint that can be safely overlaid. In this example, the renderer is located at:

/libs/wcm/core/content/sites/jcr:content/rails/references/items/references

The resourceType points to: granite/ui/references/components/coral/references which leads to the final JSP file responsible for rendering the sidebar:

/libs/granite/ui/references/components/coral/references/references.jsp

Changing the jsp

Once the correct JSP is located, it can be changed in CRX/DE. Logging can be added or new HTML tags can be added to gain insight into how the component operates.

For testing purpose let's add a new div tag with a red background to make changes visible.

<div style="background-color:red">additional text</div>

After saving the file and refreshing the browser, you may notice that the UI remains unchanged and there is no log output. The reason is that the AEM SDK for AEMaaCS ships with precompiled JSP scripts, which are bundled to ensure the UI loads quickly on the first access.

Disabling the precompiled jsp bundle

To successfully debug and apply changes, it's necessary to stop the bundle containing the precompiled scripts when using the AEMaaCS SDK

  1. Navigate to: http://localhost:4502/system/console/bundles/aem-precompiled-scripts
  2. Click the “Stop” button to put the bundle in a “Resolved” state.
  3. Refresh the View in AEM Sites http://localhost:4502/sites.html/content

You should see your changes reflected, including any new tags or logging output added.

Creating the overlay

When all necessary changes are done, the file can be copied over to the appropriate /apps path. In our case, the file would have to be copied over to

/apps/granite/ui/references/components/coral/references/references.jsp

References