The AEM HTL JavaScript Use-API: The Whys and Hows
About the Author: Cleo Anderson is an AEM Engineer at Hoodoo Digital. She has been in software development since the age of 14, creating web and desktop solutions in a variety of different languages and frameworks. Cleo has a passion for technology and problem solving, to deliver robust solutions while maintaining best practices and providing high-performance software. She utilizes a mix of creativity and understanding of every layer of software development to find unique solutions for any problem.
Adobe Experience Manager (AEM) has a few lesser-known features that can empower solution development or help handle scenarios that are project-specific. One feature included in this list of hidden gems is the HTL JavaScript Use-API, an API that allows prototyping of new or extended components, as well as creating simple solutions quickly.
What is the HTL JavaScript Use-API?
From Adobe’s own help documents, the HTL JavaScript Use-API is described as follows:
“The HTML Template Language (HTL) JavaScript Use-API enables a HTL file to access helper code written in JavaScript. This allows all complex business logic to be encapsulated in the JavaScript code, while the HTL code deals only with direct markup production.”
Effectively, this API allows for HTL component code to use a helper model written in JavaScript. Usually, these models are written in Java as a Sling model instead.
What’s the difference between the Java Use-API and the JavaScript Use-API?
Besides the clear difference of writing language between the two APIs, there are actually a lot of similarities between the two approaches. However, in some specific scenarios, JavaScript can be faster or more convenient to implement thanks to its web-native methodologies. On the other hand, AEM uses a library called Rhino to interpret the JavaScript in Java, so for large workloads or complex components, using the JavaScript API may end up running slower than a native Java counterpart.
How do I use the JavaScript Use-API as a solution?
The JavaScript Use-API is a great tool for a bunch of different business scenarios, including but not limited to:
- Creating fast and functional demo components to demonstrate intended functionality
- Using web-native methodologies and language to develop complex components
- Extending core components with small incremental changes
Instead of creating a Sling model (and possibly needing to refactor a project with new Java imports and code to handle web-native data and language, which can cause increased scope or complexity) the JavaScript Use-API allows for quick implementation of demo or web-native components without the need for additional complexities. This means a faster turnaround and increased flexibility for developing components that fit these business scenarios.
How do I develop with the JavaScript Use-API?
The quickest way to get a solid understanding of the JavaScript Use-API is to take a look at an example piece of code. Let’s assume you need to group some variables and control how the variables are returned to the HTL frontend so you can replace undefined values with safe defaults:
The first thing we do at line 1 is pass a new function into the use() function. This passes back the object we return here to the HTL page as an object with properties, just like a normal Sling model. Next, we define a container object to return back, then we define a few properties by looking at the properties object provided to us by AEM. The properties object contains all of the properties of our component’s JCR node. We use the get() function to grab each relevant property and assign it, then we finally return back the finished object. A nice feature of the get() function is we can define a default if the property is undefined, preventing odd behavior from missing values.
Then, once we’ve defined this JS file and saved it, using it is as easy as placing it in the component folder and referencing it in HTL
like so:
Another nice feature of the JavaScript Use-API is importing JS dependencies for your object to use:
The imported JS files can be either absolute paths or a path relative to the main script’s own path. This allows for importing functionality that might not be available in Java or might have an easier solution in JavaScript. However, as stated earlier, it likely is not a good idea to import large dependencies this way, as this code is interpreted at runtime and may be less performant than a Java-native solution.
Utilizing these tangential offerings from Adobe Experience Manager (AEM) empowers developers to deal with project-specific scenarios. It’s worth keeping in mind that there are several other tools available to help developers manage scenarios they will face during development. These tools have a variety of uses, including things like passing values from the HTL code back to the JavaScript Use-API code. These tools can be found at Adobe’s official help documentation on the JavaScript Use-API.
Rightpoint brings simplicity to the complexity of Adobe Experience Cloud implementations and complements it with outstanding experience design.
Utah Office:
132 S State St
Salt Lake City, UT 84111
Mailing Address:
50 W Broadway Ste 333
PMB 27084
Salt Lake City, Utah 84101-2027