Arti­cle updat­ed on May 24, 2017.

In this arti­cle I will give you some exam­ples on how to use the Val­ueMap func­tion­al­i­ty in your AEM6.x appli­ca­tion.

And I will intro­duce two good friends of the Val­ueMap that are real­ly use­ful.

By default you already have a few Val­ueMaps avail­able in your com­po­nents, these are cre­at­ed via the cq:defineObjects tag. In case you use the HTML Tem­plate Lan­guage (HTL), for­mer­ly Sight­ly, the same objects are avail­able in your com­po­nent, this with­out includ­ing any­thing extra.

This is locat­ed in the global.jsp that is by default in the “/libs/foundation” fold­er. One of the most com­mon­ly used one is “prop­er­ties”, this will expose the prop­er­ties of your com­po­nent.

Accessing Properties

When you want to get the val­ue of a prop­er­ty:


JSP: <%= properties.get("yourproperty", "default value") %>


In case you have a few nest­ed nodes you can do the fol­low­ing:


JSP: <%= properties.get("node1/node2/myproperty", "default value") %>

When the prop­er­ty isn’t found an emp­ty String will be returned.

So there is no need to do checks with­in the Node.class like you see often:

node1.hasNode("node2") && node1.getNode("node2").hasProperty("myproperty")
And with the HTML Template Language:




Getting a ValueMap

If you want to get a Val­ueMap from a Resource you have, you can do this via .adapt­To(), or use ResourceUtil.getValueMap().
ResourceU­til has some safe­ty checks that will make sure an emp­ty Val­ueMap is returned in case the Resource can’t be adapt­ed.

In AEM6.x you now also have the method get­Val­ueMap() on the Resource.

ValueMap vm = resource.adaptTo(ValueMap.class);

ValueMap vm = resource.getValueMap();

ValueMap vm = ResourceUtil.getValueMap(resource);

Friend 1: ValueMapDecorator

The first friend of the Val­ueMap is the Val­ueMapDec­o­ra­tor, this class can be used to cre­ate a cus­tom Val­ueMap that is not based on a resource.
Also this instance of a Val­ueMap allows you to call the put-method. When you do this on a Val­ueMap that is based on a resource you will get an Unsup­port­e­d­Op­er­a­tion-excep­tion.

Here is an exam­ple on how you can do this:

ValueMap props = new ValueMapDecorator(new HashMap());

props.put("test", "value");

Friend 2: InheritanceValueMap

The sec­ond friend of the Val­ueMap is the Inher­i­tance­Val­ueMap, this is a Val­ueMap that can be used if you have prop­er­ties defined at mul­ti­ple-lev­els and you want to retrieve the cor­rect one. This will avoid you to code a loop that goes through all the par­ents and checks for a cer­tain prop­er­ty.

For exam­ple if you have a page-tree where­by at every lev­el you can set the col­or, at page-lev­el you just want to get the col­or that need to be used for this page.

When you use HTL there is the object “inherit­ed­Page­Prop­er­ties” avail­able.


This is how you can cre­ate an instance of the Inher­i­tance­Val­ueMap:

InheritanceValueMap inVM = new HierarchyNodeInheritanceValueMap(page.getContentResource());

To get an val­ue by inher­i­tance sim­ply call this method:

inVM.getInherited("myproperty", "default");

Friend 3: CompositeValueMap

The third friend is the Com­pos­ite­Val­ueMap that is avail­able since AEM6.3

This allows you to merge two Val­ueMaps, for exam­ple to have a default set of prop­er­ties that can be used to com­plete the Val­ueMap that is based on the resource.

Dur­ing the instan­ti­a­tion you can merge two Val­ueMaps, after this it behaves as a nor­mal Val­ueMap.

new CompositeValueMap(request.getResource().getValueMap(), DEFAULT_PROPERTIES);

I have made a full exam­ple here: https://​github​.com/​h​e​e​r​v​i​s​s​c​h​e​r​/​h​t​l​-​e​x​a​m​p​l​e​s​/​b​l​o​b​/​m​a​s​t​e​r​/​c​o​r​e​/​s​r​c​/​m​a​i​n​/​j​a​v​a​/​c​o​m​/​a​d​o​b​e​/​e​x​a​m​p​l​e​s​/​h​t​l​/​c​o​r​e​/​m​o​d​e​l​s​/​C​o​m​p​o​s​i​t​e​V​a​l​u​e​M​a​p​M​o​d​e​l​.​j​ava

In this next arti­cle I will intro­duce the Mod­i­fi­abl­e­Val­ueMap, that makes chang­ing of prop­er­ties real­ly easy.

Hap­py cod­ing!