Article summary

Summary
Discusses the following points:
  • how to develop an AEM 6 Touch UI component. 
  • how to develop the AEM 6 component's dialog using sling:resourceType properties, which is required for use in the Touch UI view.
  • how to build a dialog for the same component for use in the AEM classic view. 
  • how to use the component in both theTouch UI and classic views. 
Digital Marketing Solution(s) Adobe Experience Manager (Adobe CQ)
Audience
Developer (beginner - intermediate)
Required Skills
JCR nodes, JavaScript, HTML
Tested On Adobe Experience Manager 6.0, 6.1

Note:

You can download an AEM package that contains the code used in this article. Download the package and deploy using package manager. The purpose of this code is to show the community these concepts in action. That is, it's to illustrate how to write an AEM Touch UI component that can be used within the AEM Touch UI. This community code is for teaching purposes only and not meant to go into production as is.

You can view the sample community application by using the following URL: http://localhost:4502/editor.html/content/TouchUIPage0.html (assuming you deploy on author).

Download

Note:

After installing this component - ensure that you add it to the side kick or side rail. This is required to drag the component from the side kick in Classic UI or the side rail in the Touch UI. See the section titled: View the AEM page in Classic UI view and populate the AEM side kick at the end of this document. 

Introduction

You can create an Adobe Experience Manager (AEM) 6 Touch UI component that can be used within the AEM Touch UI view. An AEM Touch UI component is located on the AEM Touch UI side rail. You can drag the component from the side rail onto an AEM page, as shown in this illustration.

TouchIntro

Note:

In the Touch UI environment, components are located on the side rail. In the AEM classic view, components are located in the AEM side kick. 

Once you drag the component onto the AEM page, you can access its Touch UI dialog to enter component values. For example, you can enter text that is displayed by the component, as shown in the following illustration.

TouchDialog


After you enter the component's values (for example, text values), you click the checkmark icon and the values are entered onto the AEM page. 

AEMTouch

The following illustration shows the project files created in this development article.

project
Section Description
A JCR nodes that represent the component's dialog when used in the Touch UI view.    
B JCR nodes that represent the component's dialog when used in the Classic UI view.  
C The component JSP file. You can use application logic to get the values that a user entered into dialog values.
D The  page component that lets an author drag the component from the Touch UI side rail onto an AEM web page during design time.
E The template on which the page component is based. 

This development article steps you through how to build an AEM 6 Touch UI component that lets an AEM author drag the component from the side rail onto an AEM page and set text values. Perform these steps:

  1. Create a CQ application folder structure. 
  2. Create a template on which the page component is based.
  3. Create the page component based on the template.
  4. Create an AEM 6 Touch UI component.
  5. Add a dialog to the Touch UI component. 
  6. Create a CQ web page that uses the new component.

Create an AEM application folder structure  

Create an AEM application folder structure that contains templates, components, and pages by using CRXDE Lite.  

CQAppSetup

 

The following describes each application folder:

  • application name: contains all of the resources that an application uses. The resources can be templates, pages, components, and so on.
  • components: contains components that your application uses.
  • page: contains page components. A page component is a script such as a JSP file.
  • global: contains global components that your application uses.
  • template: contains templates on which you base page components.
  • src: contains source code that comprises an OSGi component (this development article does not create an OSGi bundle using this folder).
  • install: contains a compiled OSGi bundles container.

To create an application folder structure:

  1. Go to CRXDE Lite at http://localhost:4502/crx/de/index.jsp#.
  2. Right-click the apps folder (or the parent folder), select Create, Create Folder.
  3. Enter the folder name into the Create Folder dialog box. Enter mywebsite2.
  4. Repeat steps 1-4 for each folder specified in the previous illustration.
  5. Click the Save All button.

Note:

You have to click the Save All button when working in CRXDE Lite for the changes to be made.  

Create a template 

You can create a template by using CRXDE Lite. A CQ template enables you to define a consistent style for the pages in your application. A template comprises of nodes that specify the page structure. For more information about templates, see Templates.

To create a template, perform these tasks:

1. Go to CRXDE Lite at http://localhost:4502/crx/de/index.jsp#.

2. Right-click the template folder (within your application), select Create, Create Template.

3. Enter the following information into the Create Template dialog box:

  • Label: The name of the template to create. Enter templateWeb.
  • Title: The title that is assigned to the template.
  • Description: The description that is assigned to the template.
  • Resource Type: The component's path that is assigned to the template and copied to implementing pages. Enter mywebsite2/components/page/templateWeb.
  • Ranking: The order (ascending) in which this template will appear in relation to other templates. Setting this value to 1 ensures that the template appears first in the list.

4. Add a path to Allowed Paths. Click on the plus sign and enter the following value: /content(/.*)?.

5. Click Next for Allowed Parents.

6. Select OK on Allowed Children.

Create the page component based on the template  

Components are re-usable modules that implement specific application logic to render the content of your web site. You can think of a component as a collection of scripts (for example, JSPs, Java servlets, and so on) that completely realize a specific function. In order to realize this functionality, it is your responsibility as a CQ developer to create scripts that perform specific functionality. For more information about components, see Components.

By default, a component has at least one default script, identical to the name of the component. To create a render component, perform these tasks:

1. Go to CRXDE Lite at http://localhost:4502/crx/de/index.jsp#.

2. Right-click /apps/website2/components/page, then select Create, Create Component.

3. Enter the following information into the Create Component dialog box:

  • Label: The name of the component to create. Enter templateWeb.
  • Title: The title that is assigned to the component.
  • Description: The description that is assigned to the template.
  • Super Type: foundation/components/page 

4. Select Next for Advanced Component Settings and Allowed Parents.

5. Select OK on Allowed Children.

6. Open the templateWeb.jsp located at: /apps/mywebsite2/components/page/templateWeb/templateWeb.jsp.

7. Enter the following HTML code.

<html>
<%@include file="/libs/foundation/global.jsp" %>
<cq:include script="/libs/wcm/core/components/init/init.jsp"/>
<body>
<h1>Here is where your Touch UI component will go</h1>
<cq:include path="par" resourceType="foundation/components/parsys" />
</body>
</html>

Create an AEM 6 Touch UI component

After you setup the AEM folder structure, create the AEM Touch UI component. Perform these tasks using CRXDE Lite:

1. Right click on /apps/mywebsite2/components and then select New, Component.

2. Enter the following information into the Create Component dialog box:

  • Label: The name of the component to create. Enter herotext2.
  • Title: The title that is assigned to the component. Enter herotext2.
  • Description: The description that is assigned to the template. Enter herotext2.
  • Super Resource Type: Enter foundation/components/parbase.
  • Group: The group in the side kick where the component appears. Enter General. (The herotext2 component is located under the General heading in the Tocuh UI side rail. Also appears in General in the classic view sidekick.)
  • Allowed parents: Enter */*parsys.

3. Click Ok.

Add a dialog to the AEM Touch UI component  

A dialog lets an author click on the component in the Touch UI (or Classic UI) view during design time and enter values that are used by the component. The component created in this development article lets the AEM author enter text values, which are then displayed in the AEM web page. (See the illustration shown at the beginning of this development article.)

A dialog that is built for the Touch UI is defined by using nodes of type un:structured. You define the type of control on the Touch UI dialog by setting the node's sling:resourceType property. For example, to define a text field on a Touch UI dialog, set the  sling:resourceType property to granite/ui/components/foundation/form/textfield.

The following table lists the sling:resourceType values that are used to create the component in this development article.

Sling:resourceType Description
granite/ui/components/foundation/container Defines a container for the dialog
granite/ui/components/foundation/layouts/tabs Defines a tab that is used in the dialog
granite/ui/components/foundation/section Defines a section within a tab. 
granite/ui/components/foundation/layouts/fixedcolumns Defines fixed columns. 
granite/ui/components/foundation/form/textfield Defines a text field that lets authors enter data.
granite/ui/components/foundation/form/textarea Defines a text area field that lets author more data than a text field. 

Note:

When building a dialog for the Touch UI view, you define the type of control (for example, a text field) by setting the sling:resourceType property. In contrast, when building a dialog for the classic view, you define the type of control by setting its xtype property. You set both properties in the following sections. For a listing of all Granite objects, see Granite Reference.

The following illustration shows the JCR nodes of the component created in this development article. 

dialogJCR


As you can see in the previous illustration, there are two JCR branches that are related to the component's dialog:

  • /apps/mywebsite2/components/herotext2/cq:dialog
  • /apps/mywebsite2/components/herotext2/dialog
Both of these dialogs are required when developing an AEM component. The first branch defines the component's dialog used in the Touch UI environment. The second branch defines the component's dialog used in the AEM classic view. Therefore to use the component in both AEM views, you need to create both JCR node branches.  
 

Build the dialog for the Touch UI view

Perform these tasks:

1. Select /apps/mywebsite2/components/herotext2.

2. Right click and select Create, Create Node.

3. Enter the following values:

  • Name: cq:dialog
  • Type: nt:unstructured

4. Add the following properties to the cq:dialog node.

 

Name Type Value Description
helppath String en/cq/current/wcm/
default_components.html#Carousel
Specifies the location of the help content. (see the help button on the top of the Touch UI dialog shown at the start of this article)
jcr:title
String
Hero Text
Specifies the title displayed in the dialog. (see the illustration at the start of this article)
sling:resourceType
String
cq/gui/components/authoring/dialog
Specifies the type of node. In this example, the type is a dialog.

5. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog.

6. Right click and select Create, Create Node. Enter the following values:

  • Name: content
  • Type: nt:unstructured

7. Add the following property to the content node.

Name Type Value Description
sling:resourceType String granite/ui/components/foundation/container Defines the type

8. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content.

9. Right click and select Create, Create Node. Enter the following values:

  • Name: layout
  • Type: nt:unstructured

10. Add the following properties to the layout node.

Name Type Value Description
sling:resourceType String granite/ui/components/foundation/
layouts/tabs
Defines the type
type String nav defines tab functionality

11. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content.

12. Right click and select Create, Create Node. Enter the following values:

  • Name: items
  • Type: nt:unstructured

13. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items.

14. Right click and select Create, Create Node. Enter the following values:

  • Name: herotext
  • Type: nt:unstructured
15. Add the following properties to the herotext node (this node represents the tab).
Name Type Value Description
jcr:title String Hero Text Properties The value displayed on the tab of the Touch UI dialog (see the illustration at the start of this article)
sling:resourceType String granite/ui/components/
foundation/section
Defines the tab functionality

16. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext.

17. Right click and select Create, Create Node. Enter the following values:

  • Name: layout
  • Type: nt:unstructured

18. Add the following property to the layout node.

Name Type Value Description
sling:resourceType String granite/ui/components/foundation/
layouts/fixedcolumns
defines the type of sling resource

19. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext.

20. Right click and select Create, Create Node. Enter the following values:

  • Name: items
  • Type: nt:unstructured

21. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext/items.

22. Right click and select Create, Create Node. Enter the following values:

  • Name: column
  • Type: nt:unstructured

23. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext/items/column.

24. Add the following property to the columns node. 

Name Type Value Description
sling:resourceType String granite/ui/components/foundation/container defines the type of sling resource

25. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext/items/column.

26. Right click and select Create, Create Node. Enter the following values:

  • Name: items
  • Type: nt:unstructured

27. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext/items/column/items.

28. Right click and select Create, Create Node. Enter the following values:

  • Name:headingText
  • Type: nt:unstructured

29. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext/items/
column/items/headingText
.

30. Add the following properties to the headingText node (this node represents the Heading Text input control on the dialog. See the illustration at the start of this article.)

Name Type Value Description
fieldLabel Value Heading Text Defines the label associated with the input control
name String ./jcr:Heading Defines the name of the control. You reference this value in the component's code.
sling:resourceType String granite/ui/components/
foundation/form/textfield
Defines the control as a text field. 

31. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext/items/column/items.

32. Right click and select Create, Create Node. Enter the following values:

  • Name:description
  • Type: nt:unstructured

33. Click on the following node: /apps/mywebsite2/components/herotext2/cq:dialog/content/items/herotext/
items/column/items/description.

34. Add the following property to the description node (this node represents the Description input control on the dialog. See the illustration at the start of this article.)

Name Type Value Description
fieldLabel Value Description
Defines the label associated with the input control
name String ./jcr:description
Defines the name of the control. You reference this value in the component's code.
sling:resourceType String granite/ui/components/foundation
/form/textarea
Defines the control as a text area. 

Build the dialog for the AEM classic view

Build a dialog for the classic view by performing these tasks:

  1. Select /apps/website2/components/herotext2, right click and select Create, Create Dialog.
  2. In the Title field, enter herotext2.
  3. Click Ok.
  4. Delete all nodes under /apps/website2/components/herotext2/dialog/.

Create the dialog tab

Create the first tab in the dialog titled for the herotext2 component. This dialog contains a text field control and a text area control (same controls that are located in the Touch UI dialog).     

ClassicDialog

To create the Custom xtype Multi-Field tab, perform these tasks:

1. Click on the following node: /apps/mywebsite2/components/herotext2/dialog.

2. Right click and select Create, Create Node. Enter the following values:

  • Name: items
  • Type: cq:WidgetCollection

3. Select the /apps/mywebsite2/components/herotext2/dialog/items node.

4. Right click and select Create, Create Node. Enter the following values:

  • Name: tab3
  • Type: cq:Widget

5. Click on the following node: /apps/mywebsite2/components/herotext2/dialog/items/tab3.

6. Add the following properties to the tab3 node.

Name Type Value Description
title String Text Details
The text that is displayed.
xtype String panel
Specifies the data type for this control. A panel holds other controls.

7. Click on the following node: /apps/mywebsite2/components/herotext2/dialog/items/tab3.

8. Right click and select Create, Create Node. Enter the following values:

  • Name: items
  • Type: cq:WidgetCollections.

9. Click on the following node: /apps/mywebsite2/components/herotext2/dialog/items/tab3/items.

10. Right click and select Create, Create Node. Enter the following values:

  • Name: headingText
  • Type: cq:Widget

11. Add the following properties to the headingText node.

Name Type Value Description
fieldLabel String Heading Text
The field label.
hideLabel Boolean true Specifies whether the label is hidden.
name String ./jcr:Heading
The name of the control.
xtype String textfield
Specifies the data type. A textfield lets a user enter text.

12. Click on the following node: /apps/mywebsite2/components/herotext2/dialog/items/tab3/items.

13. Right click and select Create, Create Node. Enter the following values:

  • Name: description
  • Type: cq:Widget

14. Add the following properties to the description node.

Name Type Value Description
fieldLabel
String Description The field label.
name
String ./jcr:description
The name of the control.
xtype String textarea Defines a text area control.

Add JavaScript code to the clientlib JS files

Add JavaScript logic to the herotext2 component's JSP file. All this component does is to display the values that are entered into the dialog on the AEM web page. It is important that you understand how to retrieve values that are entered into a component's dialog before building more advanced components.

Add the following application logic to the JSP file located at: /apps/mywebsite2/components/herotext2/herotext2.jsp.

<%@page session="false"%><%--
   ==============================================================================

  Hero Text component

  Combines the text and the image component

--%><%@ page import="
    com.day.cq.wcm.api.WCMMode,com.day.cq.wcm.foundation.Placeholder" %><%
%><%@include file="/libs/foundation/global.jsp"%><%

        String heading = (String)properties.get("jcr:Heading");
if (heading == null) {
    if(WCMMode.fromRequest(slingRequest) == WCMMode.EDIT) {
    	%><%= Placeholder.getDefaultPlaceholder(slingRequest, component,
		"<img src=\"/libs/cq/ui/resources/0.gif\" class=\"cq-list-placeholder\" alt=\"\">")%><%}	
}
else {
%>
		<header>
			<cq:text property="jcr:Heading" placeholder="Hero Text" tagName="h1" escapeXml="true"/>
			<cq:text property="jcr:description" placeholder="" tagName="p" tagClass="intro" escapeXml="true"/>
		</header>
<%
}
%>

In this example, notice that the text values that an author enters in the component's dialog are retrieved in these lines of code:

<header>
<cq:text property="jcr:Heading" placeholder="Hero Text" tagName="h1" escapeXml="true"/>
<cq:text property="jcr:description" placeholder="" tagName="p" tagClass="intro" escapeXml="true"/>
</header>

Notice that the names specified in the name properties jcr:Heading and jcr:description are specified in this code example. This is how text values entered into a component's dialog are displayed in an AEM web page.

 

Create an AEM web page that uses the Touch UI component 

The final task is to create a site in the AEM Touch UI view that contains a page that is based on  templateWeb (the template created earlier in this development article). This AEM page lets you select the herotext2 component that you just created from the AEM Touch UI side rail, as shown in the following illustration.

HeroText2

Likewise, you can also use the herotext2 component in the AEM classic view. In this situation, you drag the component from the CQ sidekick, as shown in the following illustration. 

 

ClassicView

To create an AEM web page that uses the Touch UI component, perform these tasks:

  1. Go to the AEM welcome page at http://[host name]:[port]; for example, http://localhost:4502.
  2. Select Sites.
  3. Select the + Icon in the web page. This create a new AEM page. 
  4. Select Create Page.
  5. Select templateWeb from the list of templates that appear. 
  6. Select Next.
  7. Specify the name of the page in the Title field.
  8. Select Create Page and open the new page. 
  9. Drag the herotext2 component from the AEM side rail into the page. Double click on the component. Enter values into the dialog. Once done, the values are displayed in the AEM web page.

Note:

If the AEM side panel is empty, populate the AEM side kick as described later in this section, when the AEM side kick is populated, the side rail is also populated with components. 

View the AEM page in Classic UI view and populate the AEM side kick

You can also view the page in AEM Classic UI view. To do so, select Classic View from the wheel icon in the AEM Page near the top, as shown in this illustration. 

ClassicView2

You will see the CQ sidekick and the herotext2 component under the General category. You can drag and drop the herotext2 component onto the CQ page.

If the CQ sidekick is empty, you can populate it by clicking the Design button located at the bottom of the sidekick. Next click the Edit button that appears and select General from the list of categories that appear as shown here.

General

To view the sidekick with the General category, click the down arrow icon that appears on the sidekick. Drag the myxtype component on the AEM web page. Double click on the component and you see the dialog that you created in this development article. 

Why components are not showing up in Sidekick

Each Experience Manager template has a different set of components that can be defined to be available for use. This allows you to control what the authors will be allowed to use, and it makes it easier for them, because they will only see the relevant components.

When looking at a page, you can switch to Design mode (as opposed to the "edit" or "preview" modes where you spend most of your time authoring the page). The Design mode allows to define the per-template specific settings. It is accessed through the yellow ruler icon on the very bottom of the sidekick.
When in design mode, click on the "Edit" button that is on the blue toolbar called "Design of par", there you'll be able to enable the components you want to be able to use.

When are you are building components, keep in mind that the design mode and the corresponding design dialogs of the components is a convenient way to define global per-template settings that you don't want to be required to be set specifically on each component instance.

The tabs at the top are missing so its not just the list of parsys components that are not getting rendered, the container of the parsys components are not getting rendered. Also, on Firefox tabs and components loads with a spinner and fades in, on Chrome the spinner starts, but the fade in doesnt happen and the Sidekick opens and closes.

See also

Congratulations, you have just created an AEM 6 Touch UI component. Please refer to the AEM community page for other articles that discuss how to build AEM services/applications.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy