First Steps for Developers

You are reading the Adobe Experience Manager 5.6.1 version of First Steps for Developers.
This documentation is also available for the following versions: AEM 5.6  CQ 5.5  CQ 5.4  CQ 5.3 

This section describes how to create your own components and add them to the paragraph system.

A quick way to get started is to copy an existing component and then make the changes you want.

An example of how to develop a component is described in detail in Extending the Text and Image Component - An Example.

Developing a new component by adapting an existing component

To develop new components for AEM based on existing component you can copy the component, create a javascript file for the new component and store it in a location accessible to AEM (see also Customizing Components and Other Elements):

  1. In the CRXDE Lite, create a new component folder in /apps/<myProject>/components/<myComponent> by copying an existing component, such as the Text component, and renaming it.
    For example, to customize the Text component copy:
        from /libs/foundation/components/text
        to /apps/myProject/components/text

    Note

    It is recommended that you save your tree before copying the new component. You can do this by pressing the Save All button in the upper left corner of the CRXDE Lite console.

  2. Modify the jcr:title to reflect its new name. This is required in order to avoid confusion with the foundation component.

  3. Open the new component folder and make the changes you require; also, delete any extraneous information in the folder.

    You can make changes such as:

    • adding a new field in the dialog box
    • replacing the .jsp file (name it after your new component)
    • or completely reworking the entire component if you want

    For example, if you take a copy of the standard Text component, you can add an additional field to the dialog box, then update the .jsp to process the input made there.

  4. Navigate to the component and verify the value of the allowedParents property is */parsys, which makes it available to the paragraph system.

    Either cq:editConfig node, dialog, or design_dialog node should be present and properly initialized for the new component to appear.

  5. Activate the new component in your paragraph system either by adding the value <path-to-component> (for example, /apps/geometrixx/components/myComponent) to the property components of the node /etc/designs/geometrixx/jcr:content/contentpage/par in CRX or by following the instructions in Adding new components to paragraph systems.

  6. In AEM WCM, open a page in your web site and insert a new paragraph of the type you just created to make sure the component is working properly.

Note

To see timing statistics for page loading, you can use Ctrl-Shift-U - with ?debugClientLibs=true set in the URL.

Adding a new component to the paragraph system (design mode)

After the component has been developed, you add it to the paragraph system, which enables authors to select and use the component when editing a page.

  1. Access a page within your authoring environment that uses the paragraph system; for example <contentPath>/Test.html.

  2. Switch to Design mode by either:

    • adding ?wcmmode=design to the end of the URL and accessing again; for example:
      <contextPath>/ Test.html?wcmmode=design
    • clicking Design in Sidekick

    You are now in design mode and can edit the paragraph system.

  3. Click Edit.

    A list of components belonging to the paragraph system are shown (all those defined with the property allowedParents=*/parsys). Your new component is also listed.

    The components can be activated (or deactivated) to determine which are offered to the author when editing a page.

  4. Activate your component, then return to normal edit mode to confirm that it is available for use.

Extending the Text and Image Component - An Example

This section provides an example on how to extend the widely used text and image standard component with a configurable image placement feature.

The extension to the text and image component allows editors to use all the existing functionality of the component plus have an extra option to specify the placement of the image either:

  • on the left-hand side of the text (current behavior and the new default)

  • as well as on the right-hand side

After extending this component, you can configure the image placement through the component's dialog box.

The following techniques are described in this exercise:

  • Copying existing component node and modifying its metadata

  • Modifying the component's dialog, including inheritance of widgets from parent dialog boxes

  • Modifying the component's script to implement the new functionality

Extending the existing textimage component

To create the new component, we use the standard textimage component as a basis and modify it. We store the new component in the Geometrixx AEM WCM example application.

  1. Copy the standard textimage component from /libs/foundation/components/textimage into the Geometrixx component folder, /apps/geometrixx/components, using textimage as the target node name. (Copy the component by navigating to the component, right-clicking and selecting Copy and browsing to the target directory.)

    file
  2. To keep this example simple, navigate to the component you copied and delete all the subnodes of the new textimage node except for the following ones:

    • dialog definition: textimage/dialog
    • component script: textimage/textimage.jsp
    • edit configuration node (allowing drag-and-drop of assets): textimage/cq:editConfig
  3. Edit the component metadata:

    • Component name
      • Set jcr:description to Text Image Component (Extended)
      • Set jcr:title to Text Image (Extended)
    • Component listing in the paragraph (parsys component) system (leave as is)
      • Leave allowedParents defined as */parsys
    • Group, where the component is listed in the sidekick (leave as is)
      • Leave componentGroup set to General
    • Parent component for the new component (the standard textimage component)
      • Set sling:resourceSuperType to foundation/components/textimage

    After this step, the component node looks like this:

    file
  4. Change the sling:resourceType property of the edit configuration node of the image (property: textimage/cq:editConfig/cq:dropTargets/image/parameters/sling:resourceType) to geometrixx/components/textimage.

    This way, when an image is dropped to the component on the page, the sling:resourceType property of the extended textimage component is set to: geometrixx/components/textimage.

  5. Modify the component's dialog box to include the new option. The new component inherits the parts of the dialog box that are the same as in the original. The only addition we make is to extend the Advanced tab, adding an Image Position dropdown list, with options Left and Right:

    • Leave the textimage/dialog properties unchanged.

    Note how textimage/dialog/items has four subnodes, tab1 to tab4, representing the four tabs of the textimage dialog box.

    • For the first two tabs (tab1 and tab2):
      • Change xtype to cqinclude (to inherit from the standard component).
      • Add a path property with values /libs/foundation/components/textimage/dialog/items/tab1.infinity.json and /libs/foundation/components/textimage/dialog/items/tab2.infinity.json, respectively.
      • Remove all other properties or subnodes.
    • For tab3:
      • Leave the properties and subnodes without changes
      • Add a new field definition to tab3/items, node position of type cq:Widget
      • Set the following properties (of type String) for the new tab3/items/position node:
        • name: ./imagePosition
        • xtype: selection
        • fieldLabel: Image Position
        • type: select
      • Add subnode position/options of type cq:WidgetCollection to represent the two choices for image placement, and under it create two nodes, o1 and o2 of type nt:unstructured.
      • For node position/options/o1 set the properties: text to Left and value to left.
      • For node position/options/o2 set the properties: text to Right and value to right.
    • Delete tab4.

    Image position is persisted in content as the imagePosition property of the node representing textimage paragraph. After these steps, the component dialog box looks like this:

    file

    Note

    For more detail on the exact purpose of the nodes and properties referenced in this example, please refer to Components and their structure.

  6. Extend the component script, textimage.jsp, with extra handling of the new parameter:

     

    1. Open the /apps/geometrixx/components/textimage/textimage.jsp script for editing.

    2. We are going to manipulate the style of the div tag, generated by the component, to float the image to the right. It is located in the following area of the code:

     

            image.addCssClass(ddClassName);
            image.setSelector(".img");
            image.setDoctype(Doctype.fromRequest(request));
    
            String divId = "cq-textimage-jsp-" + resource.getPath();
            String imageHeight = image.get(image.getItemName(Image.PN_HEIGHT));
            

    We are going to replace the emphasized code fragment %><div class="image"><% with new code generating a custom style for this tag.

    3. Copy the following code fragment, and replace the %><div class="image" section of the line with it:

    // todo: add new CSS class for the 'right image' instead of using 
    // the style attribute 
    String style="";
         if (properties.get("imagePosition", "left").equals("right")) { 
              style = "style=\"float:right\""; 
         } 
         %><div <%= style %> class="image"><%
            

    Make sure that you leave the rest of the tag intact, otherwise the script will not function.

    For simplicity, we are hard-coding the style to the HTML tag. The proper way to do it would be to add a new CSS class to the application styles and just add the class to the tag in the code in the case of a right-aligned image.

    4. Save the component to the repository. The component is ready to test.

The code fragment, after the change, should look like this:

 String ddClassName = DropTarget.CSS_CLASS_PREFIX + "image";

    if (image.hasContent() || WCMMode.fromRequest(request) == WCMMode.EDIT) {
        image.loadStyleData(currentStyle);
        // add design information if not default (i.e. for reference paras)
        if (!currentDesign.equals(resourceDesign)) {
            image.setSuffix(currentDesign.getId());
        }
        image.addCssClass(ddClassName);
        image.setSelector(".img");
        image.setDoctype(Doctype.fromRequest(request));

        String divId = "cq-textimage-jsp-" + resource.getPath();
        String imageHeight = image.get(image.getItemName(Image.PN_HEIGHT));
        // div around image for additional formatting
        String style="";
     if (properties.get("imagePosition", "left").equals("right")) {
          style = "style=\"float:right\"";
     }
     %><div <%= style %> class="image"><%
        %><% image.draw(out); %><br><%
    
        %><cq:text property="image/jcr:description" placeholder="" tagName="small" escapeXml="true"/><%
        %></div>
        <%@include file="/libs/foundation/components/image/tracking-js.jsp"%>
        <%
    }

       String placeholder = (isAuthoringUIModeTouch && !image.hasContent())
               ? Placeholder.getDefaultPlaceholder(slingRequest, component, "", ddClassName)
               : "";
    %><cq:text property="text" tagClass="text" escapeXml="true" placeholder="<%= placeholder %>"/><div
        class="clear"></div>

        

Checking the new component

After the component has been developed, you can add it to the paragraph system, which enables authors to select and use the component when editing a page. These steps allow you to test the component.

  1. Open a page in Geometrixx; for example, English / Company.

  2. Switch to design mode by clicking Design in Sidekick.

  3. Edit the paragraph system design by clicking Edit on the paragraph system in the middle of the page. A list of components, which can be placed in the paragraph system are shown, and it should include your newly developed component, Text Image (Extended) . Activate it for the paragraph system by selecting it and clicking OK .

  4. Switch back to the editing mode.

  5. Add the Text Image (Extended) paragraph to the paragraph system, initialize text and image with sample content. Save the changes.

  6. Open the dialog of the text and image paragraph, and change the Image Position on the Advanced tab to Right , and click OK to save the changes.

  7. The paragraph is rendered with the image on the right.

  8. The component is now ready to use.

The component stores its content in a paragraph on the Company page.

Disable Upload Capability of the Image Component

To disable this capability, we use the standard image component as a basis and modify it. We store the new component in the Geometrixx example application.

  1. Copy the standard image component from /libs/foundation/components/image into the Geometrixx component folder, /apps/geometrixx/components, using image as the target node name.

    file
  2. Edit the component metadata:

    • Set jcr:title to Image (Extended)
  3. Navigate to /apps/geometrixx/components/image/dialog/items/image.

  4. Add a new property:

    • Name: allowUpload
    • Type: String
    • Value: false
    file
  5. Click Save All. The component is ready to test.

  6. Open a page in Geometrixx; for example, English / Company.

  7. Switch to design mode and activate Image (Extended).

  8. Switch back to the editing mode and add it to the paragraph system. On the next pictures, you can see the differences between the original image component and the one you just created.

    Original image component:

    file

    Your new image component:

    file
  9. The component is now ready to use.


Your comments are welcome!
Did you notice a way we could improve the documentation on this page?
Please leave your comments below and we will make the appropriate changes.

COMMENTS

  • By guest - 1:19 PM on Mar 03, 2013   Reply
    Is this truly a getting started page for developers? It seems to assume a few things/prerequisites. For ex, the paragraph system has not be explained, before it is spoken of. Has each section like "Developing a new component by adapting an existing component" & "Extending the Text and Image Component - An Example" been written by different people? The level of detail in each is different.
    • By Scott Brodersen - 5:52 PM on Mar 04, 2013   Reply
      Hi,

      this page is not very well-titled. A better starting point is http://dev.day.com/docs/en/cq/current/howto/website.html.

      scott
    • By Scott Macdonald - 2:06 AM on Mar 08, 2013   Reply
      You will also find a lot of 'How Tos' to get you up and running with Adobe CQ at the Adobe CQ support and community. For example, may I suggest some of these as a developer articles (each discuss a different use case):

      http://helpx.adobe.com/adobe-cq/using/creating-custom-cq-email-services.html

      http://helpx.adobe.com/adobe-cq/using/integrating-custom-cq-widgets-third-party.html

      http://helpx.adobe.com/adobe-cq/using/cq-drag-drop-applications.html

      For other content -- see: http://helpx.adobe.com/marketing-cloud/experience-manager.html.

      Thanks

      • By Vitali - 6:57 AM on Jun 07, 2013   Reply
        There are many unclear things in this guide - it's not so obvious for beginners.
        • By zumbrunn - 7:23 AM on Jun 07, 2013   Reply
          Hi Vitali,

          We are working to improve the introductional documentation for developers. If you can point out specific areas that are unclear to you, we will try to pay attention to clarify these aspects.
        • By Liam - 8:58 AM on Aug 14, 2013   Reply
          thanks for the article, i'm working on how to build a new componement of my own....if there is a more specified tutorial about this aspect, it would be great !!
          • By aheimoz - 8:54 AM on Aug 15, 2013   Reply
            Hopefully the information under the following can help:
            http://dev.day.com/docs/en/cq/current.html#Developing%20on%20Adobe%20Experience%20Manager

            And our forum is a prime location for exchanging ideas and experiences related to AEM:
            http://help-forums.adobe.com/content/adobeforums/en/experience-manager-forum/adobe-experience-manager.html

            Hope that helps.
          • By Liam - 8:14 AM on Aug 26, 2013   Reply
            Hi

            there is one step in this tutorial i dont quite follow..
            it says "Change xtype to cqinclude (to inherit from the standard component)."
            and then Add a path property with values ........

            so basically what i need to do is change the values of Xtype to cqinclude as below for tab1 and tab2:
            xtype string cqinclude

            and then add a new property like:
            path String "whatever the address is.."

            is that correct...?
            thx for the reply

            • By Guillaume Carlino - 10:46 AM on Jan 06, 2014   Reply
              Hi Liam

              Yes this is correct.

              Guillaume
            • By Daniel - 6:26 PM on Jan 09, 2014   Reply
              The "For node position/options/o1 set the properties: text to Left and value to left.
              For node position/options/o2 set the properties: text to Right and value to right."

              Seems a bit unclear, maybe the structure of the lines should be better thought out.

              It should say for example to add o1 node with name : text, type: String and it's value: Left
              name: value, type: string and it's value: left etc...

              Such as the "name: ./imagePosition
              xtype: selection
              fieldLabel: Image Position
              type: select"

              was formatted.

              Thanks!
              • By Sarchiz - 10:01 AM on Feb 13, 2014   Reply
                Hi Daniel,


                Thanks for the suggestion. We'll work to improve the whole procedure so that it'll be less confusing in the future.
              • By sonia - 12:05 AM on Feb 17, 2014   Reply
                for Checking the new component, it is written: "Open a page in Geometrixx; for example, English / Company." It might be a dumb question but how to we open a page in Geometrixx and how do we see sidekick?
                • By Chris R - 2:00 PM on Feb 25, 2014   Reply
                  Hello. Line 16 in the fragment after the change looks problematic.

                  %><div String style="";

                  Seems to be ending a scriptlet and opening a html div tag but has the java statement inside.
                  • By Chris R - 5:52 PM on Feb 25, 2014   Reply
                    Hi. I followed these instructions as well as I could, but cannot get the dialog to open on Text Image (Extended). Fast double click opens other dialog windows on
                    http://localhost:4502/cf#/content/geometrixx-outdoors/en/company.html
                    also, I'm able to drop images and insert text, but nothing happens on double-click.
                    • By Roger C. - 5:07 PM on Feb 26, 2014   Reply
                      Just like Christ R. I could not open the dialog. Any ideas about it?

                    ADD A COMMENT

                     

                    In order to post a comment, you need to sign-in.

                    Note: Customers with DayCare user accounts need to create a new account for use on day.com.

                    ***