Overriding Project Properties

To override Project Properties, for example, those defined in the main top-root pom.xml:

<properties>
        <crx.host>localhost</crx.host>
        <crx.port>4502</crx.port>
        <crx.username>admin</crx.username>
        <crx.password>admin</crx.password>
        <publish.crx.host>localhost</publish.crx.host>
        <publish.crx.port>4503</publish.crx.port>
        <publish.crx.username>admin</publish.crx.username>
        <publish.crx.password>admin</publish.crx.password>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

Do the following at the command line:

mvn -PautoInstallPackage clean install -Dcrx.host=production.hostname -Dcrx.password=productionpasswd

Extending an existing component

To extend a component you should use the sling:resourceSuperType.

You should take a look at base components stored at: core/wcm/components/list/v2/

It is also common to change the following properties:

• jcr:title
• componentGroup

Using the Sling Resource Merger in AEM

Purpose

The Sling Resource Merger provides services to access and merge resources. It provides diff (differencing) mechanisms for both:

Overlays of resources using the configured search paths .

Overrides of component dialogs for the touch-enabled UI ( cq:dialog ), using the resource type hierarchy (by means of the property sling:resourceSuperType ).

With the Sling Resource Merger, the overlay/override resources and/or properties are merged with the original resources/properties:

• The content of the customized definition has a higher priority than that of the original (i.e. it overlays or overrides it).
• Where necessary, properties defined in the customization, indicate how content merged from the original is to be used.

The Sling Resource Merger and related methods can only be used with Granite . This also means that it is only appropriate for the stndard, touch-enabled UI; in particular overrides defined in this manner are only applicable for the touch-enabled dialog of a component.

Overlays/overrides for other areas (including other aspects of a touch-enabled component or the classic UI) involve copying the appropriate node and structure from the original to where the customization will be defined.

Goals for AEM

The goals for using the Sling Resource Merger in AEM are to:

• ensure that customization changes are not made in /libs .
• reduce the structure that is replicated from /libs .
• When using the Sling Resource Merger it is not recommended to copy the entire structure from /libs as this would result in too much information being held in the customization (usually /apps ). Duplicating information unnecessarily increases the chance of problems when the system in upgraded in any way.

Overrides are not dependent on the search paths, they use the property sling:resourceSuperType to make the connection.

However, overrides are often defined under /apps , as best practice in AEM is to define customizations under /apps ; this is because you must not change anything under /libs .

You must not change anything in the /libs path.

This is because the content of /libs is overwritten the next time you upgrade your instance (and may well be overwritten when you apply either a hotfix or feature pack).

The recommended method for configuration and other changes is:

1. Recreate the required item (i.e. as it exists in /libs ) under /apps
2. Make any changes within /apps

Properties

The resource merger provides the following properties:

• sling:hideProperties ( String or String[] )
• Specifies the property, or list of properties, to hide.
• The wildcard * hides all.
• sling:hideResource ( Boolean )
• Indicates whether the resources should be completely hidden, including its children.
• sling:hideChildren ( String or String[] )
• Contains the child node, or list of child nodes, to hide. The properties of the node will be maintained.
• The wildcard * hides all.
• sling:orderBefore ( String )
• Contains the name of the sibling node that the current node should be positioned in front of.

These properties affect how the corresponding/original resources/properties (from /libs ) are used by the overlay/override (often in /apps ).

Creating the Structure

To create an overlay or override you need to recreate the original node, with the equivalent structure, under the destination (usually /apps ). For example:

Overlay

• The definition of the navigation entry for the Sites console, as shown in the rail is defined at:
• /libs/cq/core/content/nav/sites/jcr:title
• To overlay this, create the following node:
• /apps/cq/core/content/nav/sites
• Then update the property jcr:title as required.

Override

• The definition of the touch-enabled dialog for the Texts console, is defined at:
• /libs/foundation/components/text/cq:dialog
• To override this, create the following node - for example:
• /apps/the-project/components/text/cq:dialog

To create either of these you only need to recreate the skeleton structure. To simplify the recreation of the structure all intermediary nodes can be of type nt:unstructured (they do not have to reflect the original node type; for example, in /libs ).

So in the above overlay example, the following nodes are needed:

/apps

  /cq

    /core

      /content

        /nav

          /sites

When using the Sling Resource Merger (i.e. when dealing with the standard, touch-enabled UI) it is not recommended to copy the entire structure from /libs as it would result in too much information being held in /apps . This can cause problems when the system in upgraded in any way.

Use Cases

These, in conjunction with standard functionality, enable you to:

• Add a property
• The property does not exist in the /libs definition, but is required in the /apps overlay/override.

• Create the corresponding node within /apps
• Create the new property on this node ``

Redefine a property (not auto-created properties)

The property is defined in /libs , but a new value is required in the /apps overlay/override.

• Create the corresponding node within /apps
• Create the matching property on this node (under / apps )
• The property will have a priority based on the Sling Resource Resolver configuration.
• Changing the property type is supported. If you use a property type different to the one used in /libs , then the property type you define will be used.

Changing the property type is supported.

Redefine an auto-created property

By default, auto-created properties (such as jcr:primaryType ) are not subject to an overlay/override to ensure that the node type currently under /libs is respected. To impose an overlay/override you have to recreate the node in /apps , explicitly hide the property and redefine it:

• Create the corresponding node under /apps with the desired jcr:primaryType
• Create the property sling:hideProperties on that node, with the value set to that of the auto-created property; for example, jcr:primaryType
• This property, defined under /apps , will now take priority over the one defined under /libs

Redefine a node and its children

The node and its children are defined in /libs , but a new configuration is required in the /apps overlay/override.

• Combine the actions of:
• Hide children of a node (keeping the properties of the node)
• Redefine the property/properties

Hide a property

The property is defined in /libs , but not required in the /apps overlay/override.

Create the corresponding node within /apps

Create a property sling:hideProperties of type String or String[] . Use this specify the properties to be hidden/ignored. Wildcards can also be used. For example:

• *
• ["*"]
• jcr:title
• ["jcr:title", "jcr:description"]

Hide a node and its children

The node and its children are defined in /libs , but not required in the /apps overlay/override.

• Create the corresponding node under /apps
• Create a property sling:hideResource
• type: Boolean
• value: true

Hide children of a node (while keeping the properties of the node)

The node, its properties and its children are defined in /libs . The node and its properties are required in the /apps overlay/override, but some or all of the child nodes are not required in the /apps overlay/override.

• Create the corresponding node under /apps
• Create the property sling:hideChildren :
• type: String[]
• value: a list of the child nodes (as defined in /libs ) to hide/ignore
• The wildcard * can be used to hid/ignore all child nodes.

Reorder nodes

The node and its siblings are defined in /libs . A new position is required so the node is recreated in the /apps overlay/override, where the new position is defined in reference to the appropriate sibling node in /libs .

Use the sling:orderBefore property:

• Create the corresponding node under /apps
• Create the property sling:orderBefore :
• This specifies the node (as in /libs ) that the current node should be positioned before:
• type: String
• value: <before-SiblingName>

Invoking the Sling Resource Merger from your code

The Sling Resource Merger includes two custom resource providers - one for overlays and another for overrides. Each of these can be can invoked within your code by using a mount point:

When accessing your resource it is recommended to use the appropriate mount point.

This ensures that the Sling Resource Merger is invoked and the fully merged resource returned (reducing the structure that needs to be replicated from /libs ).

Overlay:

• purpose: merge resources based on their search path
• mount point: /mnt/overlay
• usage: mount point + relative path
• example:
• getResource('/mnt/overlay' + '<relative-path-to-resource>');

Override:

• purpose: merge resources based on their super type
• mount point: /mnt/overide
• usage: mount point + absolute path
• example:
• getResource('/mnt/override' + '<absolute-path-to-resource>');

Example of Usage

Some examples are covered:

Overlay:

• Customizing the Consoles
• Customizing Page Authoring

Override:

• Configuring your Page Properties

Sling Resource Merger

The Sling Resource Merger provides services to access and merge resources. It provides diff (differencing) mechanisms for both:

• Overlays of resources using the configured search paths.
• Overrides of component dialogs for the touch-optimized UI (cq:dialog), using the resource type hierarchy (by means of the property sling:resourceSuperType).

How to override third-party OSGI Config in AEM

Overview
An overriding concept is a pretty known subject in AEM. Components can be overridden in an application with a sling resolution technique. Similarly, Apache sling has a resolution order to resolve OSGi configs as well. Basically, application-specific config’s can override AEM Libs configs. For more details on OSGI config & their resolution order, Read my posts here.

1. How does OSGi Config work?
2. AEM OSGi Config Resolution Order

Scenarios/Problems
Let’s consider a scenario of a project where you have to use another AEM Project or third-party source code like ACS Commons. And, there are some services which you want to use but with different configurations. Assume services do have configurations in place.

Now you might be thinking that what is the big deal in that. We can upload third-party code & change the configuration. Well, That is the whole point. The moment you change the configuration for your application, One more maintenance issue happens. Got it? No?

No worry. The issue is that every time you update/install third-party code for your application, You have to manually change the configuration. You might think it is okay. But it is not when you have to support the same in every environment after every deployment. Someone has to fix every time. And what if the configuration has to be updated in prod publish environment. It is tough to maintain. Let me explain with config files.

#Thirdparty config’s XML File match for ContentFeed service under config.publish folder & apps folder is /apps/abc/thirdparty/. ContentFeed Service is part of platform code base.

#Base config: com.abc.core.contentFeed.xml

<?xml version="1.0" encoding="UTF-8"?>

<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"

    jcr:primaryType="sling:OsgiConfig"

    contentFeedPath="https://example.com/api/core/platform"/>

#Your application would like to override this config. And apps are/apps/myapp etc.

#Brand specific config: com.abc.core.contentFeed.xml

<?xml version="1.0" encoding="UTF-8"?>

<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"

    jcr:primaryType="sling:OsgiConfig"

    contentFeedPath="https://example.com/api/feed<myapp-feeds>"/>

Now, ContentFeed service does not pick your application-specific config & even though you have the same config in your application. It always picks up the third party config. And it happens ContentFeed service is part of platform source code. I hope the problem is clear to you now. let’s see a solution.

General Solution
A general approach is to keep modifying third-party configs in every environment after each deployment. And, When QA reports this or that not working, a new person struggles to find why it is not working. Most of us do not remember that service configs are overridden by the deployment. The second approach is to override the full code itself with different service names & configurations. Must easy to maintain but having duplicate code & same bugs as third-party has. And fixing bugs every time something fixed in the third-party source.

Alternative Solution
The solution to the above problem is simple. Make sure your app config file name is the same as third-party config. Read about the XML config & service naming convention. AEM OSGi Config Resolution Order

To make sure Service picks your configuration, You need to create the same XML config under the same run mode folder & with additional run mode info because that is how AEM put precedence over other config’s. Let me explain with the source code.

#Third-Party config file name is com.abc.core.contentFeed.xml

folder structure is: /apps/third-party/config.publish, config.author etc.

#Your app config name must be com.abc.core.contentFeed.xml

your Folder structure for config must be: /apps/third-party/config.publish.qa, /apps/third-party/config.publish.stage etc.

I hope the solution is clear to you. The solution seems easy but it solves the general problems. 

How to Over-Ride Built-In CQ Components

CQ’s components are located in /libs.  You can over-ride them or their behavior by having your component in /apps in exactly the same path.  Eg: to configure the PDF Writer, over-ride its default configuration node at /libs/cq/config/rewriter/pdf with your configuration at /apps/cq/config/rewriter/pdf.

This method ensures that the setting will survive any software upgrades.

P.S. The PDF Writer XSL Stylesheet is at \libs\wcm\core\content\pdf\page2fo.xsl

Override/Overlay Dam Asset Metadata in AEM 6.2

Use Case: Recently I have gone through a scenario. In which I want to change the dam asset properties and want to add a new widget as well.

This image depicts the default touch ui dialog available for dam asset properties. Now I want to change/add a rootPath for tags so that I can select tags from specific hierarchy only.

This Default dialog comes from “/libs/dam/content/schemaeditors/forms/default”. But According to the AEM Best Practice, we never do any change in /libs hierarchy.

Fig: DAM Asset Property Dialog

Now I thought about the below concepts:

• I have tried to do that using Resource Merger, but it didn’t work.
  

• After that, I have tried the same using Overlay the complete hierarchy in /apps but it also didn’t work.

Solution:

In AEM 6.2 the correct way to do this is through  "metadata schema".To add/change the properties for dam asset properties, use a custom metadata schema form or modify an existing form. So I decided to go for modifying an existing form.

Below Steps we need to follow:

Step 1: Go to Projects.html.

Step 2: Click on Adobe Experience Manager

Step 3: Go to Tools and click on Assets.

Step 4: Click on Metadata Schema

Step 5:  Select Default and go to edit.

Step 6: In this Edit Form, you can see all the fields available in the metadata dialog.

Fig: Modifying Existing Form
Step 7: In the url query parameter , you can see "formpath=/conf/global/settings/dam/adminui-extension/metadataschema"

Now just change some title in dialog suppose test title and check it in the same path.

Fig: Add/Change Properties in conf Hierarchy in CRX

Now I just add the property rootPath in my tags node and when I go for any image /asset metadata.

I am able to see the title to Test Title.

Fig: Updated Dialog After Modification

And when I click on tags, I can find tags available under /etc/tags/forum.

Fig: Updated the root path for Tag widget

So This was the solution of the above problem.

How to overlay a component using sling resource merger in AEM

Sling Resource merger in aem is one of the most commonly and frequently used features of the sling after aem 6.0. Due to the limited functionality of Touch UI components, we often are required to overlay/ override a component from /libs to /apps. Earlier (before aem 6.0) in case of overlay we need to copy-paste entire component structure with node type and properties and then we make our changes which indirectly increases the overhead on /apps folder.
But as adobe is promoting to use its new ouch-optimized UI for granite components, it has changed the definition of overlay for Touch UI (Granite) components where you need to create only similar skeleton structure (where nodes can be of type nt: unstructured) and you can add, remove or modify existing node.

After completing this tutorial you will have a clear understanding of:
· What is the Sling Resource Merger.
· What's the difference between overlay, override and sling resource merger
· How to overlay a component using a sling resource merger.
What is Sling Resource Merger

Sling resource merger in aem provides us the flexibility to have a merged view of multiple other resources. The exact merging mechanism will depend on the resource picker implementation that we are using (i.e. Overlay or Override). It is a part of the sling framework and available under Felix console by name (org.apache.sling.resourcemerger). To understand in detail how sling handles resource merging you can visit Sling Resource Merger.

By using Sling Resource Merger we can:
· remove existing resource/properties from the underlying resources.
· modify existing properties/child resources of the underlying resources.
· add new properties/child resources.

What's the difference between overlay, override and sling resource merger

With AEM 6.0 onwards for Non-Granite Overlay(Classic UI) and Before AEM 6.0 Overlay is used in below manner as only classic UI was supported:-

Usually when you have to overlay a component in AEM, then you copy a component from /libs/ folder to /apps/ folder. And you can write your own customization on it like changing title, add or remove a node or change the layout of newly copied components under /apps/.

As per the default OSGI preferences, AEM uses a search path to find a resource, searching first the /apps/ branch and then the /libs branch so your newly copied components under /apps/ gets priority over /libs/. But you change this preference any time from Felix console by modifying Apache Sling Resource Resolver Factory configuration(not recommended). Overlay works on the principle of the search path.

One more important thing to note about overlay is that when you overlay a component your both component that is apps and libs will be displayed in the sidekick.
With AEM 6.0 onwards, after the introduction of Touch UI for Granite related overlay we are using Sling Resource Merger:-

Now if we have to overlay a component or use a sling resource merger for a component then we need not required to copy-paste entire component structure with node properties from libs to apps. We only need to recreate the skeleton structure. To simplify the recreation of the structure all intermediary nodes can be of type nt:unstructured (they do not have to reflect the original node type; for example, in /libs).

Note: Sling Resource Merger and its related methods can only be used with granite(Touch UI) components.

The advantages of using the Sling Resource Merger in AEM is to:
· ensure that customization changes are not made in /libs.
· reduce the structure that is replicated from /libs.

Override a component in AEM:
Overriding a component is basically extending or inheriting the component using sling:resourceSuperType property. You can override a component from /libs by creating a custom component under apps manually and adding all necessary nodes and setting the value of sling:superResourceType property to that component will inherit all the features from /libs/ component, even after the upgrade you still inherit the features of the image component.

Here we can use the sling:superResourceType for any component that you want to inherit functionality (example from project A component to ProjectB etc., not only restricted to libs).

When to use overlay/sling resource merger and when to use override totally depends upon your requirement.
How to overlay a component using sling resource merger

In this section, we are going to see how to overlay a component using a sling resource merger in aem.

Example -1 Suppose we have to overlay the Project-related node jcr:title value which is under /libs/ to /apps



· Login to Crxde.
· Go to /libs/cq/core/content/nav/projects.
-- Right-click on Projects Node.
-- Select Overlay Node.


· For safer side always select Match Node Types.


· Click Ok.
· Go to /apps/cq/core/content/nav/projects
· Select the project node and add below the property
-- Name – jcr:title
-- type – String
-- Value – Test-Project



· Click SaveAll.
· Now go to http://localhost:4502/projects.html/content/projects


Congratulations You have used Sling Resource Merger in AEM 6.2.

Note: This is a very basic example of the Sling resource merger. Some times it might happen that after overlaying the node changes are not getting reflected, it means if you change in libs changes are working but not from apps. That means the sling resource merger is not working properly.

In such a chance you might need to add URL = url.replace(“/libs/”,”/mnt/overlay/”); to tell sling explicitly to merge resource. The location of this line that you have to add depends on which component is not working usually it is in your foundation component js file. This I think is a sling resource merger bug and they will fix it soon.