Article summary

 

Summary
Discusses how to create an Adobe Experience Manager logo component that displays a company logo within an AEM web page. Included in this article is how to use an AbstractImageServlet
ital Marketing Solution(s) Adobe Experience Manager (Adobe CQ)
Audience
Developer (intermediate)
Required Skills
Java, JCR, HTML
Tested On Adobe Experience Manager 5.5, 5.6

Note:

You can download an AEM package that contains 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 Logo component. This community code is for teaching purposes only and not meant to go into production as is.You can view the application by using the following URL: http://localhost:4502/cf#/content/LogoPage.html (assuming you deploy on author). 

Introduction

You can create an Adobe Experience Manager (AEM) Logo component that displays your companies logo in an AEM web site. A logo component can also provide a link to the home page of your AEM web site. A logo component also contains a design-mode dialog so that property values are stored in the site design (/etc/designs/mywebsite):

  • The property values apply to all instances of the component that are added to pages that use the design.
  • The properties can be configured using any instance of the component that is on a page that uses the design.
  • Your design-mode dialog contains properties for setting the image and the link path. The logo component will be placed on the upper left side of all pages in the website.

A logo component lets an author select a logo during design-time, as shown in the following illustration. 

LogoDesign

When the author selects the image, it is displayed within the AEM web page, as shown in the following illustration. 

Logo

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

projectfiles

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 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 logosite.
  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 page component 

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 (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 templateLogo
  • 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 logosite/components/page/templateLogo.
  • 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 page render component

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 templateLogo
  • 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/logosite/components/page/templateLogo/templateLogo.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 Logo Component will go</h1>
<cq:include path="logo" resourceType="logosite/components/logo" />
<cq:include path="par" resourceType="foundation/components/parsys" />
</body>
</html>

Note:

The logosite/components/logo resource type is created in the remainder of this article. 

Create a logo component

After you setup the AEM folder structure, create the AEM logo componentd. Perform these tasks using CRXDE Lite:

1. Right click on /apps/logosite/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 logo.
  • Title: The title that is assigned to the component. Enter logo.
  • Description: The description that is assigned to the template. Enter logo component.

3. Click Next until you reach the final panel of the dialog and then click OK.

Add a Design Mode Dialog to the AEM logo component

A design-mode dialog lets an author click on the component during design time and enter values that are used by the component. In this use case, the author selects an image that is used as the logo that is displayed in the AEM web page. A design-mode dialog nodes must be named design_dialog (as shown in the illustration at the beginning of this article).

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

  1. Select /apps/logosite/components/logo, right click and select Create, Create Dialog.
  2. In the Title field, enter design_dialog.
  3. Click Ok.
  4. Delete the tab1 node under /apps/logosite/components/logo/design_dialog/items/items.
  5. Click on the following node: /apps/logosite/components/logo/design_dialog/items/items.
  6. Right click and select Create, Create Node. Enter the following values:
    • Name: img
    • Type: cq:Widget
  7. Select the /apps/logosite/components/logo/design_dialog/items/items/img node.
  8. Add the following properties to the img node.

 

Name Type Value Description
fileNameParameter
String
./imageName
Name of the form field used for posting the file name
fileReferenceParameter
String ./imageReference
Name of the form field used for posting the file reference. 
name String ./image
The field's HTML name attribute.
title String Image
The title text to be used as innerHTML.
xtype String html5smartimage
Specifies the data type of the control. The value selection corresponds to CQ.form.SmartImage. For information, see Class CQ.form.SmartImage.

Creating the logo Java render script

Create the script that retrieves the logo image and writes it to the page. The Java class extends AbstractImageServlet. You can use this servelt when working with images in AEM components. Make sure that the package that you use in the Java file matches the node path of the component. In this example, the package is apps.logosite.components.logo. See Class AbstractImageServlet

Perform these tasks.

1. Right-clck the logo component node and click Create, Create File to create the script file named img.GET.java.

2. Add the following code to this file.

package apps.logosite.components.logo;

import java.io.IOException;
import java.io.InputStream;

import javax.jcr.RepositoryException;
import javax.jcr.Property;
import javax.servlet.http.HttpServletResponse;

import com.day.cq.wcm.foundation.Image;
import com.day.cq.wcm.commons.RequestHelper;
import com.day.cq.wcm.commons.WCMUtils;
import com.day.cq.wcm.commons.AbstractImageServlet;
import com.day.cq.commons.SlingRepositoryException;
import com.day.image.Layer;
import org.apache.commons.io.IOUtils;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.SlingHttpServletResponse;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ValueMap;
import org.apache.sling.api.servlets.SlingSafeMethodsServlet;

/**
 * Renders an image
 */
public class img_GET extends AbstractImageServlet {

    protected Layer createLayer(ImageContext c)
            throws RepositoryException, IOException {
        // don't create the layer yet. handle everything later
        return null;
    }

    protected void writeLayer(SlingHttpServletRequest req,
                              SlingHttpServletResponse resp,
                              ImageContext c, Layer layer)
            throws IOException, RepositoryException {

        Image image = new Image(c.resource);
        image.setItemName(Image.NN_FILE, "image");
        image.setItemName(Image.PN_REFERENCE, "imageReference");
        if (!image.hasContent()) {
            resp.sendError(HttpServletResponse.SC_NOT_FOUND);
            return;
        }
        // get pure layer
        layer = image.getLayer(false, false, false);

        // do not re-encode layer, just spool
        Property data = image.getData();
        InputStream in = data.getStream();
        resp.setContentLength((int) data.getLength());
        String contentType = image.getMimeType();
        if (contentType.equals("application/octet-stream")) {
            contentType=c.requestImageType;
        }
        resp.setContentType(contentType);
        IOUtils.copy(in, resp.getOutputStream());
        in.close();
      
        resp.flushBuffer();
    }
}

Modify the Logo JSP file

Modify the JSP of the logo component. Using CRXDE lite, open the following file:

/apps/logosite/components/logo/logo.jsp

Add the following JSP code to this file.

<%@include file="/libs/foundation/global.jsp"%><%
%><%@ page import="com.day.text.Text,
                   com.day.cq.wcm.foundation.Image,
                   com.day.cq.commons.Doctype" %><%
    /* obtain the path for home */
    long absParent = currentStyle.get("absParent", 2L);
    String home = Text.getAbsoluteParent(currentPage.getPath(), (int) absParent);
    /* obtain the image */
    Resource res = currentStyle.getDefiningResource("imageReference");
    if (res == null) {
        res = currentStyle.getDefiningResource("image");
    }
    /* if no image use text link, otherwise draw the image */
    %>
<a href="<%= home %>.html"><%
    if (res == null) {
        %>Home<%
    } else {
        Image img = new Image(res);
        img.setItemName(Image.NN_FILE, "image");
        img.setItemName(Image.PN_REFERENCE, "imageReference");
        img.setSelector("img");
        img.setDoctype(Doctype.fromRequest(request));
        img.setAlt("Home");
        img.draw(out);
    }
    %></a>

Create an AEM web page that displays the logo component

The final task is to create a site that contains a page that is based on the templateLogo (the template created earlier in this development article). You use the design mode dialog to select the image that is used as a logo. 

 

LogoDesign


Create a CQ web page that displays the custom logo 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 templateLogo 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. 
  7. With the templateLogo page open in your browser, click the Design button at the bottom of Sidekick to enter design mode. 
  8. In the Design of logo bar, click Edit to use the dialog to edit the settings for the logo component.
  9. In the dialog, click in the panel of the Image tab, browse for the image to use. 
  10. Click the triangle on the Sidekick title bar to return to Edit mode.

See also

Congratulations, you have just created a custom AEM logo component. Now that you understand how to build a custom component, 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