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 that contains event handlers

In addition to this article - it's recommended that you watch the Touch UI webinar. This is the April session of Ask the AEM communtiy experts

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

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 uses event handlers. 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/TouchUIEvents.html (assuming you deploy on author).

Download

Introduction

When developing Adobe Experience Manager (AEM) Touch UI components, handling events is an important task. In AEM 6, the Touch UI APIs do not have event handler methods. For information about the AEM Touch UI APIs, see Granite UI documentation.

As a result, to handle events, use DOM supported events. You can use JQuery to handle events. For example, the following code represents the event handler that is invoked when the Touch UI dialog is opened:

$document.on("dialog-ready", function() {
        $(window).adaptTo("foundation-ui").alert("Open", "Dialog now open, event [dialog-ready]");
    });

This event handler produces an alert message box that appears when the Touch UI dialog is opened, as shown in the following illustration.

dialog

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. 

In AEM 6, the Granite API does not support event handler methods. Therefore you have to define an event handler using DOM events and JQuery. You define event handlers in JS scripts located in AEM client library (this is shown later in this development article).  

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

projectFiles
Section Description
A JCR nodes that represent the component's client libs folder. In this folder, JS script defines application logic that handles events.     
B JCR nodes that represent the component's Touch UI dialog.  
C The component JSP file.
D 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 responds to dialog events. 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.

Note:

If you install the package shown at the begining of this artilce, you can skip these steps. 

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. To view the CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
  2. Select CRXDE Lite.
  3. Right-click the apps folder (or the parent folder), select Create, Create Folder.
  4. Enter the folder name into the Create Folder dialog box. Enter touchevents.
  5. Repeat steps 1-4 for each folder specified in the previous illustration.
  6. 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. To view the CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.

2. Select CRXDE Lite.

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

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

  • Label: The name of the template to create. Enter templateEvents.
  • 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 touchevents/components/page/templateEvents.
  • 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.

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

6. Click Next for Allowed Parents.

7. 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. To view the CQ welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.

2. Select CRXDE Lite.

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

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

  • Label: The name of the component to create. Enter templateEvents.
  • Title: The title that is assigned to the component.
  • Description: The description that is assigned to the template.
  • Super Type: foundation/components/page (in AEM 6, you specify this value for page components. In previous versions of AEM, this was not rquired.)

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

6. Select OK on Allowed Children.

7. Open the templateWeb.jsp located at: /apps/touchevents/components/page/templateEvents/templateEvents.jsp.

8. 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 that responds to events 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/touchevents/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 heroevents.
  • Title: The title that is assigned to the component. Enter heroevents.
  • Description: The description that is assigned to the template. Enter heroevents.
  • Super Resource Type: Enter foundation/components/parbase.
  • Group: The group in the side kick where the component appears. Enter General. (The heroevemts component is located under the General heading in the Touch 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 illustrates dialog events.  The following dialog events are used in this article:

  • dialog-ready - fires when the dialog is ready
  • click  -fires when the user clicks on the dialog
  • dialog-closed - fires when the dialog is closed

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. 

dialognodes


Build the dialog for the Touch UI view

Perform these tasks:

1. Select /apps/touchevents/components/heroevents.

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.

  • helppath (String) - en/cq/current/wcm/default_components.html#Text
  • jcr:title (String)  - Touch UI Dialog Listeners
  • sling:resourceType (String) - cq/gui/components/authoring/dialog

 

5. Click on the following node: /apps/touchevents/components/heroevents/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.

  • sling:resourceType (String) - granite/ui/components/foundation/container

8. Click on the following node: /apps/touchevents/components/heroevents/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.

  • sling:resourceType (String) - granite/ui/components/foundation/layouts/tabs
  • type (String) - nav

11. Click on the following node: /apps/touchevents/components/heroevents/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/touchevents/components/heroevents/cq:dialog/content/items.

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

  • Name: column
  • Type: nt:unstructured
15. Add the following properties to the column node.
  • sling:resourceType (String) - granite/ui/components/foundation/container

16. Click on the following node: /apps/touchevents/components/heroevents/cq:dialog/content/items/column.

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

  • Name: items
  • Type: nt:unstructured

 

Add a cq:ClientLibraryFolder node

Create a cq:ClientLibraryFolder node to that stores script that defines event handlers. Add this property to the clientlib node.

  • categories (String[]) - cq.authoring.dialog

To add required files to the clientlibs folder, perform these tasks:

  1. Right-click /apps/weatherappJSON/components then select New, Node.
  2. Make sure the node type is cq:ClientLibraryFolder and name the node clientlibs.
  3. Right click on clientlibs and select Properties. Add the property specified in the previous table to the node. 
  4. Add a JS file to the clientlibs folder named listeners.js (the content of this file is shown in the next section).
  5. Add a TXT file to the clientlibs node named js.txt (add listeners.js to this file).

Add JavaScript code to the clientlib JS files

Add JavaScript logic to the listeners.js file. This file defines JavaScript logic that defines event handlers fo the TOuch UI component. Add the following the code to the JS file at: /apps/touchevents/components/clientlib/listeners.js.

(function ($, $document) {
    "use strict";

      $document.on("dialog-ready", function() {
        $(window).adaptTo("foundation-ui").alert("Open", "Dialog now open, event [dialog-ready]");
    });

    $(document).on("click", ".cq-dialog-submit", function (e) {
        //$(window).adaptTo("foundation-ui").alert("Close", "Dialog closed, selector [.cq-dialog-submit]");
    });

    $document.on("dialog-ready", function() {
        document.querySelector('form.cq-dialog').addEventListener('submit', function(){
            //$(window).adaptTo("foundation-ui").alert("Close", "Dialog closed, selector [form.cq-dialog]");
        }, true);
    });

    $document.on("dialog-success", function() {
        //$(window).adaptTo("foundation-ui").alert("Save", "Dialog content saved, event [dialog-success]");
    });

    $document.on("dialog-closed", function() {
        $(window).adaptTo("foundation-ui").alert("Close", "Dialog closed, event [dialog-closed]");
    });
})($, $(document));

Touch UI Component JSP

Add the following code to the JSP file at /apps/touchevents/components/heroevents/heroevents.jsp:

 

<%@ page import="java.io.PrintWriter" %>
<%@include file="/libs/foundation/global.jsp" %>
<%@page session="false" %>

<div style="display: block; border-style: solid; border-width: 1px; margin: 10px; padding: 10px">
    <b>AEM Example Touch UI Dialog Listeners</b>

    <br><br>
</div>

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  templateEvents (the template created earlier in this development article). This AEM page lets you select the heroevents component that you just created from the AEM Touch UI side rail, as shown in the following illustration.

TouchUIEvents

When you drop the component onto the page and open the dialog, an event handler is fired and you will see a message box.  

 

dialog

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 templateEvents 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 heroevents compnent from the AEM side rail into the page. Double click on the component and notice the event handler that is fired.

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 heroevents 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.  

See also

Congratulations, you have just created an AEM 6 Touch UI component that uses event handlers. 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