Understanding the JavaScript Use-API for AEM

Adobe Experience Manager offers two APIs for writing server-side code that Sightly can consume. One is the Java Use-API and the other is the JavaScript Use-API. Developers familiar with programming for Adobe Experience Manager (also known as Adobe CQ) before AEM 6.0 will have no issues picking up the Java Use-API. The JavaScript Use-API is the new kid on the block and allows developers to write server-side JavaScript.

When I first jumped into using the JavaScript Use-API, I felt a bit lost. Not because I wasn’t familiar with JavaScript, but because I was unaware of all I really had available to me. My lack of understanding of the technology behind the API made it seem really limited. The intent of this article is to clear up that confusion and give some examples of how to take advantage of this new feature.

The first and most important thing to understand is what drives the JavaScript engine for the Use-API. Behind the scenes, AEM has implemented Rhino. According to the Rhino documentation, “Rhino is an open-source implementation of JavaScript written entirely in Java.” In a nutshell, Rhino takes JavaScript and converts it to Java.

So what good does this knowledge give us? Because our JavaScript will end up being Java, we have Java libraries available to us. Having these libraries available to use makes the JavaScript Use-API much more viable. When I first started out, I assumed I would need to write a good deal of functionality to get some of the basic features that are available in the Java Use-API. I was really making things hard on myself.

With an understanding of the JavaScript engine, let’s jump into some examples. I have created a simple component called “example”. This component will be used to display the data we return from our JavaScript file. I created two files within the component, example.html and example.js. Here is the initial code:
HTML – example.html

JS – example.js

“use strict”;
use(function() {

There are a few things to note here. The JavaScript is included in the HTML by using the data-sly-use attribute. I have defined the variable name I want to use by appending it after data-sly-use; in this case it is “example”. I also define the path to my JavaScript file. The data-sly-unwrap attribute removes the <div> from the rendered output. The JS sets the scripting mode to strict and calls the use method that accepts a function as a parameter. The function will contain any code needed for the component.

There are two ways to access component properties. If we are trying to get the jcr:title property we would do one of the following:


example.title = granite.resource.properties["jcr:title"];
example.title = properties.get("jcr:title");

Two objects were available to us from the Use-API, granite.resource.properties and properties. The trick here is that they are not the same type of object. granite.resource.properties is a Plain Old Java Object, however properties is a JcrPropertyMap. Notice that these are both Java Objects (not JavaScript). Remember, in the end, because of Rhino, we are really using Java. Because these end up being Java Objects, you can rely on the Javadocs for any additional information on how to use them. For example, a JcrPropertyMap has different method signatures for the get method. In JavaScript, I could access properties in different ways using the get method:


var example = {};

// Example 1
example.title = properties.get("jcr:title");
// Example 2 - Set default value
example.title = properties.get("jcr:title", "Hello World");

return example;

As was stated earlier, Java classes are accessible through our JavaScript. In JavaScript, there is no import statement for bringing in additional classes. Instead, to access a class, simply use its classpath. For example, to take advantage of the difference method in Java’s StringUtils, I would write the following:

// JS
var cat = "siamese";
var dog = "siberian husky";

var difference = org.apache.commons.lang.StringUtils.difference(cat, dog);

In addition to this, the Use-API has some common variables available right off the bat. These are familiar to AEM developers who have used the default global.jsp.

  • currentNode
  • currentPage
  • resource
  • log
  • sling
  • pageProperties
  • properties
  • pageManager
  • component
  • designer
  • currentDesign
  • currentStyle

For additional information on what each of these variables contain, see the AEM docs: http://docs.adobe.com/docs/en/cq/5-6-1/developing/scripts.html.

Remember the old adage, “knowing is half the battle.” Knowing what is available to you in the JavaScript Use-API should springboard you into development. I recommend jumping in and trying this new feature in a project. As a general rule, when using the JavaScript Use-API, stick to writing as much core JavaScript as possible. Take advantage of all the JavaScript library has; only jumping into the Java world when needed. The Javadocs and Rhino documentation are great resources if you get stuck. Also look at Adobe’s documentation for additional clarification and use case examples. Send us an email to info@aempodcast.com is you have any questions about the JavaScript USE-API. Also, feel free to check out our interview with Gabriel Walt about Sightly.

One thing to note before deciding to use Sightly and the JavaScript Use-API is potential performance issues. The following Sling ticket was pointed out to me following the writing of this article: Sling-4093. As of the creation of this ticket, there were significant performance hits when using Sightly over JSPs. Performance tests showed JSP running up to 10x faster than Sightly. Please be mindful of this, as you decide which technology stack to pursue.

Rhino Photo by aiace used under CC BY / Aritcle title overlays original as a text banner