In this chapter we will explore the underlying technology of an Adobe Experience Manager (AEM) Sites Component through a simple HelloWorld
example. Small modifications will be made to an existing component, covering topics of authoring, HTL, Sling Models, Client-side libraries.
Review the required tooling and instructions for setting up a local development environment.
In this chapter you will perform several modifications to a very simple HelloWorld
component. In the process of making updates to the HelloWorld
component you will learn about the key areas of AEM component development.
This chapter builds upon a generic project generated by the AEM Project Archetype. Watch the below video and review the prerequisites to get started!
Open a new command line terminal and perform the following actions.
In an empty directory, clone the aem-guides-wknd repository:
$ git clone git@github.com:adobe/aem-guides-wknd.git
Cloning into 'aem-guides-wknd'...
Optionally, you can download the component-basics/start
branch directly.
Navigate into the aem-guides-wknd
directory:
$ cd aem-guides-wknd
Switch to the component-basics/start
branch:
$ git checkout component-basics/start
Branch component-basics/start set up to track remote branch component-basics/start from origin.
Switched to a new branch 'component-basics/start'
Build and deploy the project to a local instance of AEM with the following command:
$ mvn -PautoInstallSinglePackage clean install
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for aem-guides-wknd 0.0.1-SNAPSHOT:
[INFO]
[INFO] aem-guides-wknd .................................... SUCCESS [ 0.394 s]
[INFO] WKND Sites Project - Core .......................... SUCCESS [ 7.299 s]
[INFO] WKND Sites Project - UI Frontend ................... SUCCESS [ 31.938 s]
[INFO] WKND Sites Project - Repository Structure Package .. SUCCESS [ 0.736 s]
[INFO] WKND Sites Project - UI apps ....................... SUCCESS [ 4.025 s]
[INFO] WKND Sites Project - UI content .................... SUCCESS [ 1.447 s]
[INFO] WKND Sites Project - All ........................... SUCCESS [ 0.881 s]
[INFO] WKND Sites Project - Integration Tests Bundles ..... SUCCESS [ 1.052 s]
[INFO] WKND Sites Project - Integration Tests Launcher .... SUCCESS [ 1.239 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
Import the project into your preferred IDE by following the instructions to set up a local development environment.
Components can be thought of as small modular building blocks of a web page. In order to re-use components, the components must be configurable. This is accomplished via the author dialog. Next we will author a simple component and inspect how values from the dialog are persisted in AEM.
Below are the high level steps performed in the above video.
>
US >
en.cq:dialog
and helloworld.html
script located at /apps/wknd/components/content/helloworld
.HTML Template Language or HTL is a light-weight, server-side templating language used by AEM components to render content.
Next we will update the HelloWorld
HTL script to display an additional greeting before the text message.
Below are the high level steps performed in the above video.
Switch to the Eclipse IDE and open the project to the ui.apps
module.
Open the .content.xml
file that defines the dialog for the HelloWorld
component at:
<code>/aem-guides-wknd/ui.apps/src/main/content/jcr_root/apps/wknd/components/content/helloworld/_cq_dialog/.content.xml
Update the dialog to add an additional textfield named Greeting with a name of ./greeting
:
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
jcr:primaryType="nt:unstructured"
jcr:title="Properties"
sling:resourceType="cq/gui/components/authoring/dialog">
<content
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
<items jcr:primaryType="nt:unstructured">
<column
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/container">
<items jcr:primaryType="nt:unstructured">
<greeting
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
fieldLabel="Greeting"
name="./greeting"/>
<text
jcr:primaryType="nt:unstructured"
sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
fieldLabel="Text"
name="./text"/>
</items>
</column>
</items>
</content>
</jcr:root>
Open the file helloworld.html
, which represents the main HTL script responsible for rendering the HelloWorld
component, located at:
<code>/aem-guides-wknd.ui.apps/src/main/content/jcr_root/apps/wknd/components/content/helloworld/helloworld.html
Update helloworld.html
to render the value of the Greeting textfield as part of an H1
tag:
<h1 data-sly-test="${properties.text && properties.greeting}">${properties.greeting} ${properties.text}</h1>
<pre data-sly-use.hello="com.adobe.aem.guides.wknd.core.models.HelloWorldModel">
HelloWorldModel says:
${hello.message}
</pre>
Deploy the changes to a local instance of AEM using the Eclipse Developer plugin or using your Maven skills.
Sling Models are annotation driven Java “POJO’s” (Plain Old Java Objects) that facilitate the mapping of data from the JCR to Java variables, and provide a number of other niceties when developing in the context of AEM.
Next, we will make some updates to the HelloWorldModel
Sling Model in order to apply some business logic to the values stored in the JCR before outputting them to the page.
Open the file HelloWorldModel.java
, which is the Sling Model used with the HelloWorld
component.
<code>/aem-guides-wknd.core/src/main/java/com/adobe/aem/guides/wknd/core/models/HelloWorldModel.java
Add the following lines to the HelloWorldModel
class to map the values of the component’s JCR properties greeting
and text
to Java variables:
...
@Model(adaptables = Resource.class)
public class HelloWorldModel {
...
@ValueMapValue(injectionStrategy=InjectionStrategy.OPTIONAL)
protected String greeting;
@ValueMapValue(injectionStrategy=InjectionStrategy.OPTIONAL)
protected String text;
@PostConstruct
protected void init() {
...
Add the following method getGreeting()
to the HelloWorldModel
class, that returns the value of the property named greeting
. This method adds the additional logic to return a String value of “Hello” if the property greeting
is null or blank:
/***
*
* @return the value of greeting, if null or blank returns "Hello"
*/
public String getGreeting() {
return StringUtils.isNotBlank(this.greeting) ? this.greeting : "Hello";
}
Add the following method getTextUpperCase()
to the HelloWorldModel
class, that returns the value of the property named text
. This method transforms the String to all upperCase characters.
/***
*
* @return All caps variation of the text value
*/
public String getTextUpperCase() {
return StringUtils.isNotBlank(this.text) ? this.text.toUpperCase() : null;
}
Update the file helloworld.html
at aem-guides-wknd.ui.apps/src/main/content/jcr_root/apps/wknd/components/content/helloworld/helloworld.html
to use the newly created methods of the HelloWorld
model:
<div class="cmp-helloworld" data-sly-use.hello="com.adobe.aem.guides.wknd.core.models.HelloWorldModel">
<h1 data-sly-test="${hello.textUpperCase}">${hello.greeting} ${hello.textUpperCase}</h1>
<pre>
HelloWorldModel says:
${hello.message}
</pre>
</div>
Deploy the changes to a local instance of AEM using the Eclipse Developer plugin or using your Maven skills.
Client-Side Libraries, clientlibs for short, provides a mechanism to organize and manage CSS and JavaScript files necessary for an AEM Sites implementation. Client-side libraries are the standard way to include CSS and JavaScript on a page in AEM.
Next, we will include some CSS styles for the HelloWorld
component in order to understand the very basics of client-side libraries.
Below are the high level steps performed in the above video.
beneath /aem-guides-wknd.ui.apps/src/main/content/jcr_root/apps/wknd/components/content/helloworld
create a new node named clientlibs
with a node type of cq:ClientLibraryFolder
.
Create a folder and file structure like the following beneath clientlibs
/helloworld
/clientlibs
/css/helloworld.css
/js/helloworld.js
+js.txt
+css.txt
Populate helloworld/clientlibs/css/helloworld.css
with the following:
.cmp-helloworld h1 {
color: red;
}
Populate helloworld/clientlibs/css.txt
with the following:
#base=css
helloworld.css
Populate helloworld/clientlibs/js/helloworld.js
with the following:
console.log("hello world!");
Populate helloworld/clientlibs/js.txt
with the following:
#base=js
helloworld.js
Update the clientlibs
node properties to include the following two properties:
Name | Type | Value |
---|---|---|
categories | String | wknd.base |
allowProxy | Boolean | true |
<?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="cq:ClientLibraryFolder"
categories="wknd.base"
allowProxy="{Boolean}true"/>
Deploy the changes to a local instance of AEM using the Eclipse Developer plugin or using your Maven skills.
Congratulations, you have just learned the basics of component development in Adobe Experience Manager!
Get familiar with Adobe Experience Manager pages and templates in the next chapter Pages and Templates. Understand how Core Components are proxied into the project and learn advanced policy configurations of editable templates to build out a well-structured Article Page template.
View the finished code on GitHub or review and deploy the code locally at on the Git brach component-basics/solution
.
component-basics/solution
branch