Article summary

 

Summary
Discusses how to create an AEM component that displays DAM digital assets in 3D. An example use case for this component is a website for a company that sells cars. Instead of displaying static images of cars, you can display 3D images that a user can rotate and view the car from different views.
ital Marketing Solution(s) Adobe Experience Manager (Adobe CQ)
Audience
Developer (intermediate)
Required Skills
JQuery, CSS, HTML
Tested On Adobe Experience Mananager 5.5, 5.6

Introduction

You can create an Adobe Experience Manager (AEM) component that displays digital assets located in the AEM Digial Assets Manager (DAM) in 3D. The AEM DAM lets users across an organization 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 https://helpx.adobe.com/experience-manager/6-3/assets/user-guide.html.

By displaying AEM DAM assets in 3D, your website visitors can engage with your site by clicking on and rotating images. Assume, for example, that you are developing an Adobe AEM component for a company that sells cars. The component developed in this development article lets visitors to the website obtain an engaging experience by clicking on a car image and rotating the image. This action lets a website visitor view the car from different angles.  

Car

Create an Experience Mananager 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 CQ 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 car.
  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 for the CQ 3D DAM component 

You can create a template by using CRXDE Lite. An Experience Manager 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 (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 templateCar
  • 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 car/components/page/templateCar.
  • 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 templateCar

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 (if you are using AEM 5.6, click Tools from the left menu).

3. Right-click /apps/car/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 templateCar
  • Title: The title that is assigned to the component.
  • Description: The description that is assigned to the template.

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

6. Select OK on Allowed Children.

7. Open the templateCar.jsp located at: /apps/car/components/page/templateCar/templateCar.jsp.

8. Enter the following JSP code.  

<html>
<%@include file="/libs/foundation/global.jsp" %>
<cq:include script="/libs/wcm/core/components/init/init.jsp"/>
<body>
<h1>Here is where the custom 3D AEM DAM component will go</h1>
<cq:include path="par" resourceType="foundation/components/parsys" />
</body>
</html>

Upload the digital assets to the AEM DAM 

Download a ZIP file  from the following URL:

http://voidcanvas.com/3deye/

This ZIP file contains the JS file. Download a second ZIP file that cotains the PNG images that you upload to the AEM DAM.

http://voidcanvas.com/3deye-js-a-plugin-to-create-360-degree-3d-panoramic-view-works-in-all-major-browsers-and-mobile-devices/

Extract this ZIP file to a local folder.

In the images folder, there are 51 images. Upload all 51 images to the following AEM DAM location:

/content/dam/car

After you upload these images into the AEM DAM, you can use them in the AEM 3D image component. The following illustration shows the /content/dam/car location.

DAM

Note:

By default, the images are named 1.png, 2.png, and 3.png and so on. Change the file names to car1.png, car2.png, and car3.png. If you do not change the file names, then the 3D component does not work.

To upload the car images to the AEM DAM, perform these tasks:

  1. To view the AEM DAM page, enter the URL http://localhost:4502/damadmin.
  2. Click New, New File to add digital assets.
  3. 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.)
  4. Click Upload to upload the selected assets.
  5. Activate each asset by clicking on the row and clicking the Activate button.  

Add the JQuery 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 component JSP. Add the following JS files to the folder:

  • jquery.js
  • 3deye.min.js

You can locate these files in the ZIP file that you downloaded in a previous step.

Note:

In addition to the JS files, you have to also upload the style.css file to the clientlibs folder. You can also obtain the file from the ZIP file that you downloaded.

To add CSS files and JQuery framework files to your component, add a cq:ClientLibraryFolder node to your component. After you create the node, add these two properties to the node. 

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

The dependencies property informs CQ to include the CSS files and JQuery libraries in the page. The categories property informs CQ 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 two text files to the clientlibs folder. These text files map to the JS files and the CSS file. The names of the text files are: css.txt and js.txt. The css.txt file contains the CSS file name: style.css. Likewise, the js.txt file contains the JS file names: jquery.js and 3deye.min.js.

Add the files to the ClientLibs folder

  1. Right-click /apps/car/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 file. 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.
  7. Add a TXT file to the clientlibs node named css.txt. Add the content specified in this section.

Create the DAM 3D componet

Create the AEM component that uses a displays AEM assets in 3D. Perform these tasks using CRXDE Lite:

1. Right click on /apps/appCar/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 3DCar.
  • Title: The title that is assigned to the component. Enter 3DCar.
  • Description: The description that is assigned to the template. Enter 3D DAM Component.
  • Super Resource Type: Enter foundation/components/parbase.
  • Group: The group in the side kick where the component appears. Enter General. (The 3DCar component is located under the General heading in the sidekick.)
  • Allowed parents: Enter */*parsys.

3. Click Ok.

Add a dialog to the 3D component  

A dialog lets an author click on the component during design time and enter values that are used by the component. The component created in this development article lets a user an AEM web page author specify the message that appears below the 3D image. The default message is: Rotate the car image.  

The following illustration shows the dialog that corresponds to the AEM DAM 3D component.

Dialog3


To add a dialog to the 3D component, perform these tasks:

  1. Select /apps/car/components/3DCar, right click and select Create, Create Dialog.
  2. In the Title field, enter 3dCar.
  3. Click Ok.
  4. Delete the tab1 node under /apps/car/components/3DCar/dialog/items/items.

 

Creating the dialog panel  

You build the controls on this dialog panel by setting nodes and properties. Once done, your dialog resembles the following illustration.  

dialogTree


To create the dialog tab, perform these tasks:

1. Click on the following node: /apps/hook/components/3DCar/dialog/items/items.
2. Right click and select Create, Create Node. Enter the following values:

  • Name: style
  • Type: cq:Panel

3. Select the /apps/hook/components/3DCar/dialog/items/items/style node.
4. Add the following property to the style node.

Name Type Value Description
title String 3D Car component
Specifies the title displayed on the dialog tab.

5. Select the /apps/car/components/3DCar/dialog/items/items/style node.
6. Right click and select Create, Create Node. Enter the following values:

  • Name: items
  • Type: cq:WidgetCollection

7. Select the /apps/car/components/3DCar/dialog/items/items/style/items node.
8. Right click and select Create, Create Node. Enter the following values:

  • Name: path
  • Type: cq:Widget

9. Add the following properties to the path node.

Name Type Value Description
defaultValue
String
Rotate the car image
The default value for the text field.
fieldLabel String Enter the message
Specifies the field label that is displayed.  
name String ./path Specifies the name of the control. You can reference this value in component’s JavaScript file to get the value of this field.
xtype String textfield Specifies the data type of the control. The value selection corresponds to CQ.Ext.form.TextField. For information, see CQ.Ext.form.TextField.

Add JavaScript logic to the 3DCar JSP file

Add Javascript application logic to the 3D component JSP file located at: /apps/car/components/3DCar/3DCar.jsp. Add the following JavaScript logic to this file.  

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

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

<script type="text/javascript">
$(document).ready(function(){
    
    $("#myCar").vc3dEye({
        imagePath:"/content/dam/car/car",
        totalImages:51,
        imageExtension:"png"
    });
    
});
</script>
 
</head>
 
<body>
        
        <div id="myCar">
        </div>
        <h2><%=properties.get("path", "Spin the image!!") %></h2>
</body>
</html>

There are a couple of points to note about this JavaScript code. First, notice that a reference to the ClientLibs folder that contains the JQuery files is established with this line of code:

<cq:includeClientLib categories="jquerycar" />

Next, notice in the document's ready method, the 3D plugin call is made. This is how it is possible to create a 3D image of AEM DAM assets.  

$(document).ready(function(){
   
    $("#myCar").vc3dEye({
        imagePath:"/content/dam/car/car",
        totalImages:51,
        imageExtension:"png"
    });

Notice that the AEM DAM path where the car images are stored is specified. The imagePath field is assigned /content/dam/car/car. The totalImages field specifies the number of files in the AEM DAM location that are used. In this use case, there are 51 PNG files. Finally the file's extension is specified. In this use case, it is .png.

Finally the value that the user entered in to the component's dialog is retrieved by using this method:

properties.get("path", "Move the car using your mouse!!")

The value that the user entered into the dialog is displayed in the web page.

Modify the 3DCar.jsp file:

  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 (If you are using AEM 5.6, click Tool in the left menu).
  3. Double-click /apps/car/components/3DCar/3DCar.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 image gallery component

The final task is to create a site that contains a page that is based on the templateCar (the template created earlier in this development article). This AEM page will let you select the 3D component that you just created from the CQ sidekick, as shown in the following illustration.

 

page3D


Note:

After you drop the component onto the web page, you need to refresh the page to see the car image.

When you drop the component onto the AEM web page, you can rotate the image and view it from different angles.

CarBack

Create a CQ web page that displays the custom CQ image gallery component:

  1. Go to the CQ Website page at http://localhost:4502/siteadmin#/content.
  2. Select New Page.
  3. Specify the title of the page in the Title field.
  4. Specify the name of the page in the Name field.
  5. Select templateCar 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.
  6. 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.

See also

Congratulations, you have just created a 3D component that uses AEM DAM assets. Now that you understand how to build a custom component that uses AEM DAM assets and JQuery, you can build more advanced components that you can place on the AEM sidekick and use in AEM web pages.   

Please refer to the AEM community page for more 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