Article summary

Summary

Discusses how to develop a custom carousal component. 

A special thank you to community members Ranta Kumar Kotla for testing this Community Article to ensure it works.

Digital Marketing Solution(s) Adobe Experience Manager (Adobe CQ)
Audience
Developer (beginner - intermediate)
Required Skills
JCR nodes, JavaScript, HTML
Version Adobe Experience Manager 5.x 6.x
Video N/A

Introduction

You can create a custom carousel component for Adobe Experience Manager. A carousel component displays images that can be retrieved from the Adobe Digital Asset Manager (DAM). The Experience Manager DAM is a digital asset management tool that is fully integrated with Experience Manager and enables your enterprise to share and distribute digital assets. Users across an organization can manage, store, and access images, videos, documents, audio clips, and rich media such as Flash files for use on the web, in print, and for digital distribution. For more information, see Digital Asset Management. 

Assume, for example, that you are developing an Experience Manager visual carousel component for a travel company interested in creating an online digital marketing campaign. The component lets visitors to the web site obtain an engaging experience by viewing different travel images within a rotating carousal component. 

carousel
A carousel component that displays digital assets from the AEM DAM

Notice that this carousel component displays images retrieved from the Experience Manager DAM. Each image is displayed for a pre-defined time period and then the next image is displayed. The component rotates through an established list of images and then starts over. This development article guides you through how to build this carousel component by using JQuery.

Create an Experience Manager application folder structure

Your first step is to create an application folder structure that contains templates, components, and pages by using CRXDE Lite. 

CQAppSetup

 

This list 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 (common may be a substitute for global).
  • templates: Contains templates that you can base page components on.
  • src: Contains source code that comprises an OSGi component (this example does not use an OSGi component).
  • install: Contains a compiled OSGi bundles container.

Create an application folder structure in CRXDE Lite by performing these tasks:

  1. Go to the welcome page at http://[host name]:[port]; 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 carousel.
  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 welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
2. Select CRXDE Lite (if you are using AEM 5.6, click Tools from the left menu).
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 templateCarousel
  • 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 carousel/components/page/templateCarousel.
  • 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 a render component that is based on templateCarousel

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 welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
2. Select CRXDE Lite (if you are using AEM 5.6, click Tools from the left menu).
3. Right-click /apps/carousel/components, 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 templateCarousel. 
  • Title: The title that is assigned to the component.
  • Description: The description that is assigned to the template.
  • Super Type: foundation/components/page

5. Select Next for Advanced Component Settings and Allowed Parents.
6. Select OK on Allowed Children.
7. Open the templateGallery.jsp located at: /apps/carousel/components/page/templateCarousel/templateCarousel.jsp.
8. Enter the following JSP code.
 

<html>
<head>
<title>Adobe Experience Manager Carousel Component</title>
</head>
<body>
<h1>Experience Manager Carousel !!!</h1>
<h2>This page will become a custom carousel that retrieves assets from the Experience Manager DAM</h2>
</body>
</html>

Upload the digital assets to the Experience Manager DAM  

Upload images that you use in your carousel component into the Experience Manager DAM. In this example, the pixel size of the image is 1600 (height) by 1100 (width). The images that are used in this development article contains images that promote an Alaskan cruise. The file name of these images are 1.jpg, 2.jpg, 3,jpg, 4, jpg, and 5.jpg.

The images are stored in the following DAM location:

/content/dam/travel

After you upload the images into the Experience Manager DAM, you can use it in the custom carousel component. The following illustration shows the /content/dam/travel location.

DAM
The Experience Manager Digital Asset Manager

To upload an image to the AEM DAM, perform these tasks:

  1. To view the welcome page, enter the URL http://[host name]:[port] into a web browser. For example, http://localhost:4502.
  2. Click Websites (if you are using AEM 5.6, click Tools from the left menu). Click the Digital Assets button located in the top panel (this button is shown in the previous illustration).
  3. In the Digital Assets folder, navigate to the location where you want to add digital assets.
  4. Click New, New File to add digital assets.
  5. Click Browse to locate the file and click Select. You can continue to upload multiple files. If you decide that you do not want to upload an asset, click Clear to delete it. (Internet Explorer users need to select files one by one by using the file dialog in order to upload multiple assets at the same time.)
  6. Click Upload to upload the selected assets.
     

Note:

If you are following along with this development article, you can use your own images to replace the travel images. Ensure that you set the pixel size of the thumbnail images and large images to the pixel size specified in this section. Also, place the images in the DAM location specified in this section.  

Add the JQuery Carousel API to a CQ:ClientLibraryFolder node

You add CSS files and JQuery framework files to a cq:ClientLibraryFolder node to define the style of the client JSP. The JQuery framework file that is added is named jquery-1.6.3.min.js.

In addition to the JQuery framework file, add the JQuery Carousel API library. This library enables you to create an Experience Manager widget that retrieves images from the Experience Manager DAM and displays the images within a carousel.

You can download the Carousel API library from the following URL:

You need to retrieve the following JS file from the downloaded file: jquery.infinitecarousel.js.  To add CSS files and JQuery framework files to your component, add a cq:ClientLibraryFolder node to your component. After you create the node, set properties that allow the JSP script to find the CSS files and the JQuery library files.

To add the JQuery framework, add a new node named clientlibs to your component (as discussed later). Add these two properties to this node.

Name Type Value
dependencies   String[] cq.jquery  
categories   String[] jquerysamples  

The dependencies property informs Experience Manager to include the CSS files and JQuery libraries in the page. The categories property informs Experience Manager which clientlibs must be included.

After you create the Clientlibs folder, add the stlye.css file, the JQuery library files, and two map text files.

Text files

You have to add a text file to the clientlibs folder that maps to the JS files. The name of the text file is: js.txt. The js.txt file contains the JS file names: jquery-1.6.3.min.js and jquery.infinitecarousel.js.

Add the files to the ClientLibs folder 

  1. Right-click /apps/carousel/components then select New, Node.
  2. Make sure that the node type is cq:ClientLibraryFolder and name the node clientlibs.
  3. Right click on clientlibs and select Properties. Add the two properties specified in the previous table to the node.
  4. On your file system, navigate to the folder where the JQuery JS files are located. Drag and drop the JS files to the clientlibs node by using CRXDE.
  5. On your file system, navigate where you placed the CSS files. Drag and drop the CSS files to the clientlibs folder by using CRXDE.
  6. Add a TXT file to the clientlibs folder named js.txt. Add the content specified in this section.

Modify the templateCarousel component to use the JQuery Carousel API 

Modify the templateCarousel JSP to use the JQuery Carousel API and reference the digital assets that you uploaded to the Experience Manager DAM. To reference a digital asset located in the Experience Manager DAM from your JSP, use the following URL:

/content/dam/travel/1.jpg

This URL references an image named 1.jpg that is used to populate the background of the page. To reference the thumbnail image, use the following URL:

/content/dam/travel/thumbs/1.jpg

The following code represents the templateCarousel.jsp file that contains JQuery Carousel API logic.

<%@include file="/libs/foundation/global.jsp"%>
<cq:includeClientLib categories="jquerysamples" />
<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Adobe Experience Manager Custom Carousel Demo</title>

<script type="text/javascript">
$(function(){
    $('#carousel').infiniteCarousel({
        displayTime: 6000,
        textholderHeight : .25
    });
});
</script>
<style type="text/css">
body {
    padding-top: 50px;
}
#carousel {
    margin: 0 auto;
    width: 400px;
    height: 390px;
    padding: 0;
    overflow: scroll;
    border: 2px solid #999;
}
#carousel ul {
    list-style: none;
    width: 1500px;
    margin: 0;
    padding: 0;
    position: relative;
}
#carousel li {
    display: inline;
    float: left;
}
.textholder {
    text-align: left;
    font-size: small;
    padding: 6px;
    -moz-border-radius: 6px 6px 0 0;
    -webkit-border-top-left-radius: 6px;
    -webkit-border-top-right-radius: 6px;
}
</style>
</head>

<body>

<div id="carousel">
    <ul>
        <li><img alt="" src="/content/dam/travel/1.jpg" width="500" height="213" /><p>Image 1.</p>
        </li>
        <li><img alt="" src="/content/dam/travel/2.jpg" width="500" height="213" /><p>Image 2</p>
        </li>
         <li><img alt="" src="/content/dam/travel/3.jpg" width="500" height="213" /><p>Image 3</p>
        </li>
        <li><img alt="" src="/content/dam/travel/4.jpg" width="500" height="213" /><p>Image 4</p>
        </li>
         <li><img alt="" src="/content/dam/travel/5.jpg" width="500" height="213" /><p>Image 5</p>
        </li>
    </ul>
</div>
<h3>This is an AEM example that uses five images retrieved from the AEM DAM and displayed within a custom Carousel component.</h3>

</body>
</html>

Modify the templateCarousel file 

  1. To view the welcome page, enter the URL: http://[host name]:[port] into a web browser. For example, http://localhost:4502.
  2. Select CRXDE Lite (If you are using AEM 5.6, click Tool in the left menu).
  3. Double-click apps/carousel/components/page/templateCarousel/templateCarousel.jsp.
  4. Replace the JSP code with the new code shown in this section.
  5. Click Save All.

Create an AEM web page that displays the custom carousel component

The final task is to create a site that contains a page that is based on the templateCarousel (the template created earlier in this development article).   

carouselApp
The custom carousel component that is displayed within an AEM web page

Create an Experience Manager web page that displays the custom carousel component:

  1. Go to the welcome page at http://[host name]:[port]; for example, http://localhost:4502.
    Select Websites. (If you are using AEM 5.6, click Tools from the menu on the left.)
  2. From the left hand pane, select Websites.
  3. Select New Page.
  4. Specify the title of the page in the Title field.
  5. Specify the name of the page in the Name field.
  6. Select templateCarousel from the template list that appears. This value represents the template that is created in this development article. If you do not see it, then repeat the steps in this development article. For example, if you made a typing mistake when entering in path information, the template will not show up in the New Page dialog box.
  7. Open the new page that you created by double-clicking it in the right pane. The new page opens in a web browser. You should see a page similar to the previous illustration.

Note:

The objective of this article was to demonstrate how to develop a custom carousel component for Adobe Experience Manager. You can further extend this example by placing the component within the AEM sidekick and hooking it into an Experience Manager dialog.  For information, see http://helpx.adobe.com/experience-manager/using/integrating-custom-carousel-component-cq.html.

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