Components

This page provides an overview of AEM components. The following pages provide more detailed information:

What exactly is a Component?

Components:

  • are modular units which realize specific functionality to present your content on your website
  • are re-usable
  • are developed as self-contained units within one folder of the repository
  • have no hidden configuration files
  • can contain other components
  • can run anywhere within any AEM system. They can also be limited to run under specific components
  • have a standardized user interface
  • use widgets
  • have an edit behaviour that can be configured

As components are modular, you can develop a new component on your local instance, then deploy this seamlessly to your test, then live environments.

Each AEM component:

  • is a resource type
  • is a collection of scripts that completely realize a specific function
  • can function in "isolation"; this means either within AEM or a portal

Components included with AEM include:

  • paragraph system
  • header
  • image, with accompanying text
  • toolbar

Properties and Child Nodes of a Component

A component is a node of type cq:Component and has the following properties and child nodes:

Name
Type
Description
.
 cq:Component Current component. A component is of node type cq:Component.
 componentGroup  String Group under which the component can be selected in the Sidekick.
 cq:cellName  String If set, this property is taken as Cell Id. For more information, please refer to this article in the Knowledge Base.
 cq:isContainer  Boolean Checks if this component is a container component. For example a paragraph system component.
 cq:noDecoration  Boolean If true, the component is not rendered with automatically generated div and css classes.
 cq:templatePath  String Path to a node to use as a content template when the component is added from Sidekick. This must be an absolute path, not relative to the component node.
Unless you want to reuse content already available elsewhere, this is not required and cq:template is sufficient (see below)
 dialogPath  String Path to a dialog in case that the component does not have a dialog node.
 jcr:created  Date Date of creation of the component.
 jcr:description  String Description of the component.
 jcr:title  String Title of the component.
 sling:resourceSuperType  String When set, the component inherits from this component.
 <breadcrumb.jsp>  nt:file
Script file.
 design_dialog  cq:Dialog  Definition of the design dialog.
 cq:childEditConfig  cq:EditConfig When the component is a container, as for example a paragraph system, this drives the edit configuration of the child nodes.
 cq:editConfig  cq:EditConfig Edit configuration of the component.
 cq:htmlTag  nt:unstructured  Returns additional tag attributes that are added to the surrounding html tag. Enables addition of attributes to the automatically generated divs. See Modify the auto-generated DIVs using cq:htmlTag blog post.
 cq:template  nt:unstructured If found, this node will be used as a content template when the component is added from Sidekick.
 dialog  nt:unstructured
Definition of the edit dialog.
 icon.png  nt:file Icon of the component, appears next to the Title in Sidekick.
 thumbnail.png  nt:file  Optional thumbnail that is shown while the component is dragged into place from Sidekick.
 virtual sling:Folder  Enables creation of virtual components. To see an example, please look at the contact component at /libs/foundation/components/profile/form/contact.

Default Components within AEM

AEM comes with a variety of out-of-the-box components that provide comprehensive functionality for website authors. These components and their usage within the installed "Geometrixx" website are a reference on how to implement and use components. The components are provided with all source code and can be used as is or as starting point for modified or extended components.

To get a list of all the components available in the repository, proceed as follows:

  1. In CRXDE Lite, select Tools from the toolbar, then Query; the Query tab will be opened.
  2. As Type, select XPath.
  3. In the Query input field, enter following string:
    //element(*, cq:Component)
  4. Click Execute. The list is displayed.

For detailed information on all the default components, including those that are not available out-of-the-box in AEM, see Default Components.

Components and their structure

Component definitions

As already mentioned, the definition of a component can be broken down into:

  • AEM components are based on Sling
  • AEM components are located under /libs/foundation/components
  • site specific components are located under /apps/<sitename>/components
  • AEM has the page component; this is a particular type of resource which is important for content management.
  • AEM standard components are defined as cq:Component and have the elements:
    • a list of jcr properties; these are variable and some may be optional though the basic structure of a component node, its properties and subnodes are defined by the cq:Component definition
    • the dialog defines the interface allowing the user to configure the component
    • the child node cq:editConfig (of type cq:EditConfig) defines the edit properties of the component and enables the component to appear in the Sidekick.
      Note: if the component has a dialog, it will automatically appear in the Sidekick, even if the cq:editConfig does not exist.
    • resources: define static elements used by the component 
    • scripts are used to implement the behavior of the resulting instance of the component
    • thumbnail: image to be shown if this component is listed within the paragraph system

If we take the text component, we can see these elements:

file

Properties of particular interest include:

 

  • jcr:title - title of the component; for example, appears in the component list within sidekick
  • jcr:description - description for the component; again appears in the component list within sidekick
  • icon.png - graphics file to be used as an icon for the component in Sidekick
  • thumbnail.png - graphics file to be used as a thumbnail for the component while dragging it from Sidekick

Child nodes of particular interest include:

 

  • cq:editConfig (cq:EditConfig) - this controls visual aspects; for example, it can define the appearance of a bar or widget, or can add customized controls
  • cq:childEditConfig(cq:EditConfig) - this controls the visual aspects for child components that do not have their own definitions
  • dialog (nt:unstructured) - defines the dialog for editing content of this component
  • design_dialog (nt:unstructured) - specifies the design editing options for this component

Dialogs

Dialogs are a key element of your component as they provide an interface for authors to configure and provide input to that component.

Depending on the complexity of the component your dialog may need one or more tabs - to keep the dialog short and to sort the input fields.

   

file

Within a dialog, a cq:WidgetCollection (items) is used to provide a base for either input fields (cq:Widget) or further tabs (cq:Widget). This hierarchy can be extended.

Component definitions and the content they create

If we create an instance of the Text paragraph (as above) on the <content-path>/Test.hml page:

file

then we can see the structure of the content created within the repository:

file

In particular, if you look at the text:

  • the definition of /libs/foundation/components/text/dialog/items/tab1/items/text has the property name=./text
  • within the content, this generates the property title holding the input Test Text.

The properties defined are dependent on the individual definitions, which although they can be more complex than above, follow the same basic principles.

Component Hierarchy and Inheritance

Components within AEM are subject to 3 different hierarchies:

  • Resource Type Hierarchy:
    This is used to extend components using the property sling:resourceSuperType. This enables the component to inherit; for example a text component will inherit various attributes from the standard component.
    • scripts (resolved by Sling)
    • dialogs
    • descriptions (including thumbnail images, icons, etc)
  • Container Hierarchy :
    This is used to populate configuration settings to the child component and is most commonly used in a parsys scenario.
    For example, configuration settings for the edit bar buttons, control set layout (editbars, rollover), dialog layout (inline, floating) can be defined on the parent component and propagated to the child components.
    Configuration settings (related to edit functionality) in cq:editConfig and cq:childEditConfig are propagated.
  • Include Hierarchy
    This is imposed at runtime by the sequence of includes.
    This hierarchy is used by the Designer, which in turn acts as the base for various design aspects of the rendering; including layout information, css information, the available components in a parsys among others.

Summary

The following summary applies for every component.

Summary:

  • Location: /apps/<myApp>/components

Root Node:

  • <mycomponent> (cq:Component) - Hierarchy node of the component.

Vital Properties:

  • jcr:title - Component title; for example, used as a label when the component is listed within the sidekick.
  • jcr:description - Component description; for example, also shown in the component list of the sidekick.
  • icon.png - Icon for this component.

Vital Child Nodes:

  • cq:editConfig (cq:EditConfig) - Controls author UI aspects; for example, bar or widget appearance, adds custom controls.
  • cq:childEditConfig (cq:EditConfig) - Controls author UI aspects for child components that do not define their own cq:editConfig.
  • dialog (cq:Dialog) - Content editing dialog for this component.
  • design_dialog (cq:Dialog) - Design editing for this component.

Developing Components

A quick way to get started is to copy an existing component and then make the changes you want. Read Developing Components to know how to create your own components and add them to the paragraph system.

Moving Components to the Publish Instance

The components that render content must be deployed on the same AEM instance as the content. Therefore, all components that are used for authoring and rendering pages on the author instance must be deployed on the publish instance. When deployed, the components are available to render activated pages.

Use the following tools to move your components to the publish instance:

Scripts

JSP Scripts or Servlets are usually used to render components.

According to the request processing rules of Sling the name for the default script is <componentname>.jsp.

global.jsp

The JSP script file global.jsp is used to provide quick access to specific objects (i.e. to access content) to any JSP script file used to render a component.

Therefore global.jsp should be included in every component rendering JSP script where one or more of the objects provided in global.jsp are used.

Remarque

 

Since CQ 5.3, the correct global.jsp path changed to /libs/foundation/global.jsp.

Note that the path /libs/wcm/global.jsp, which was used by earlier versions, is now obsolete.

Function of global.jsp, used APIs and Taglibs

The following lists the most important objects provided from the default global.jsp (/libs/foundation/global.jsp)

Summary:

  • <cq:defineObjects />
    • slingRequest - The wrapped Request Object (SlingHttpServletRequest).
    • slingResponse - The wrapped Response Object (SlingHttpServletResponse).
    • resource - The Sling Resource Object (slingRequest.getResource();).
    • resourceResolver - The Sling Resource Resolver Object (slingRequest.getResoucreResolver();).
    • currentNode - The resolved JCR node for the request.
    • log - The Default logger ().
    • sling - The Sling script helper.
    • properties - The properties of the addressed resource (resource.adaptTo(ValueMap.class);).
    • pageProperties - The properties of the page of the addressed resource.
    • pageManager - The page manager for accessing AEM content pages (resourceResolver.adaptTo(PageManager.class);).
    • component - The component object of the current AEM component..
    • designer - The designer object for retrieving design information (resourceResolver.adaptTo(Designer.class);).
    • currentDesign - The design of the addressed resource.
    • currentStyle - The style of the addressed resource.

Accessing Content

There are three methods to access content in AEM WCM:

  • Via the properties object introduced in global.jsp:
    The properties object is an instance of a ValueMap (see Sling API) and contains all properties of the current resource.
    Example: String pageTitle = properties.get("jcr:title", "no title"); used in the rendering script of a page component.
    Example: String paragraphTitle = properties.get("jcr:title", "no title"); used in the rendering script of a standard paragraph component.
  • Via the currentPage object introduced in global.jsp:
    The currentPage object is an instance of a page (see AEM API). The page class provides some methods to access content.
    Example: String pageTitle = currentPage.getTitle();
  • Via currentNode object introduced in global.jsp:
    The currentNode object is an instance of a node (see JCR API). The properties of a node can be accessed by the getProperty() method.
    Example: String pageTitle = currentNode.getProperty("jcr:title");

JSP Tag Libraries

The CQ and Sling tag libraries give you access to specific functions for use in the JSP script of your templates and components.

For more information, read Tag Libraries

Using Client-Side HTML Libraries

Modern websites rely heavily on client-side processing driven by complex JavaScript and CSS code. Organizing and optimizing the serving of this code can be a complicated issue.

To help deal with this issue, AEM provides Client-side Library Folders, which allow you to store your client-side code in the repository, organize it into categories, and define when and how each category of code is to be served to the client. The client-side library system then takes care of producing the correct links in your final webpage to load the correct code.

Read Using Client-Side HTML Libraries for more information.

Configuring the Edit Behaviour of a Component

This section explains how to configure the edit behaviour of a component.

The edit behaviour of a component is configured by adding a cq:editConfig node of type cq:EditConfig below the component node (of type cq:Component) and by adding specific properties and child nodes. The following properties and child nodes are available:

cq:editConfig node properties:

  • cq:actions (String array): defines the actions that can be performed on the component.
  • cq:layout (String): : defines how the component is edited.
  • cq:dialogMode (String): defines how the component dialog is opened.
  • cq:emptyText (String): defines text that is displayed when no visual content is present.
  • cq:inherit (Boolean): defines if missing values are inherited from the component that it inherits from.

cq:editConfig child nodes:

  • cq:dropTargets (node type nt:unstructured): defines a list of drop targets that can accept a drop from an asset of the content finder.
  • cq:actionConfigs (node type nt:unstructured): defines a list of new actions that are appended to the cq:actions list.
  • cq:formParameters (node type nt:unstructured): defines additional parameters that are added to the dialog form.
  • cq:inplaceEditing (node type cq:InplaceEditingConfig): defines an inplace editing configuration for the component.
  • cq:listeners (node type cq:EditListenersConfig): defines what happens before or after an action occurs on the component.

Remarque

In this page, a node (properties and child nodes) is represented as XML, as shown in the following example.

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afteredit="REFRESH_PAGE"/>
</jcr:root>
        

Les exemples de code sont fournis à titre d’illustration seulement.

There are many existing configurations in the repository. You can easily search for specific properties or child nodes:

  • To look for a property of the cq:editConfig node, e.g. cq:actions, you can use the Query tool in CRXDE Lite and search with the following XPath query string:
    //element(cq:editConfig, cq:EditConfig)[@cq:actions]
  • To look for a child node of cq:editConfig, e.g. cq:dropTargets which is of type cq:DropTargetConfig, you can use the Query tool in CRXDE Lite and search with the following XPath query string:
    //element(cq:dropTargets, cq:DropTargetConfig)

Configuring with cq:EditConfig Properties

cq:actions

The cq:actions property (String array) defines one or several actions that can be performed on the component. The following values are available:

Property Value Description
text:<some text> Displays the static text value <some text>
- Adds a spacer
edit Adds a button to edit the component
delete Adds a button to delete the component
insert Adds a button to insert a new component before the current one
copymove Adds a button to copy and cut the component

The following configuration adds an edit button, a spacer, a delete and an insert button to the component edit bar:

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    cq:actions="[edit,-,delete,insert]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>
        

Les exemples de code sont fournis à titre d’illustration seulement.

The following configuration adds the text "Inherited Configurations from Base Framework" to the component edit bar:

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    cq:actions="[text:Inherited Configurations from Base Framework]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>
        

Les exemples de code sont fournis à titre d’illustration seulement.

cq:layout

The cq:layout property (String) defines how the component can be edited. The following values are available:

Property Value Description
rollover (default value). The component edition is accessible "on mouse over" through clicks and/or context menu.
For advanced use, note that the corresponding client side object is: CQ.wcm.EditRollover.
editbar The component edition is accessible through a toolbar.
For advanced use, note that the corresponding client side object is: CQ.wcm.EditBar.
auto The choice is left to the client side code.

The following configuration adds an edit button to the component edit bar:

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>
        

Les exemples de code sont fournis à titre d’illustration seulement.

cq:dialogMode

The component can be linked to an edit dialog. The cq:dialogMode property (String) defines how the component dialog will be opened. The following values are available:

Property Value Description
floating The dialog is floating.
inline (default value). The dialog is anchored over the component.
auto If the component width is smaller than the client side CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH value, the dialog is floating, otherwise it is inline.

The following configuration defines an edit bar with an edit button, and a floating dialog:

<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>
        

Les exemples de code sont fournis à titre d’illustration seulement.

cq:emptyText

The cq:emptyText property (String) defines text that is displayed when no visual content is present.

It defaults to: "Drag components or assets here".

cq:inherit

The cq:inherit property (boolean) defines if missing values are inherited from the component that it inherits from.

It defaults to false.

Configuring with cq:EditConfig Child Nodes

cq:dropTargets

The cq:dropTargets node (node type nt:unstructured) defines a list of drop targets that can accept a drop from an asset of the content finder. It serves as a collection of nodes of type cq:DropTargetConfig.

Each child node of type cq:DropTargetConfig defines a drop target in the component. The node name is important because it must be used in the JSP as follows to generate the CSS class name assigned to the DOM element that is the effective drop target:

<drop target css class> = <drag and drop prefix> + <node name of the drop target in the edit configuration>

The <drag and drop prefix> is defined by the Java property  com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX.

For example, the class name is defined as follows in the JSP of the Download component (/libs/foundation/components/download/download.jsp):
    String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";
"file" being the node name of the drop target in the edit configuration of the Download component.

The node of type cq:DropTargetConfig needs to have the following properties:

Property Name Property Value
accept Regex applied to the asset mime type to validate if dropping is allowed.
groups Array of drop target groups. Each group must match the group type that is defined in the content finder extension and that is attached to the assets.
propertyName Name of the property that will be updated after a valid drop.

The following configuration is taken from the Download component. It enables any asset (the mime-type can be any string) from the media group to be dropped from the content finder into the component. After the drop, the component property fileReference is being updated:

    <cq:dropTargets jcr:primaryType="nt:unstructured">
        <file
            jcr:primaryType="cq:DropTargetConfig"
            accept="[.*]"
            groups="[media]"
            propertyName="./fileReference"/>
    </cq:dropTargets>
        

Les exemples de code sont fournis à titre d’illustration seulement.

cq:actionConfigs

The cq:actionConfigs node (node type nt:unstructured) defines a list of new actions that are appended to the list defined by the cq:actions property. Each child node of cq:actionConfigs defines a new action by defining a widget. The default widget type is CQ.Ext.Button.

The following sample configuration defines two new buttons:

  • a separator, defined by the xtype tbseparator.
  • a button named "Manage comments" that runs the function CQ_collab_forum_openCollabAdmin().
<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
    cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
    jcr:primaryType="cq:EditConfig">
    <cq:actionConfigs jcr:primaryType="nt:unstructured">
        <separator0
            jcr:primaryType="nt:unstructured"
            xtype="tbseparator"/>
        <manage
            jcr:primaryType="nt:unstructured"
            handler="function(){CQ_collab_forum_openCollabAdmin();}"
            text="Manage comments"/>
    </cq:actionConfigs>
</jcr:root>
        

Les exemples de code sont fournis à titre d’illustration seulement.

cq:formParameters

The cq:formParameters node (node type nt:unstructured) defines additional parameters that are added to the dialog form. Each property is mapped to a form parameter.

The following configuration adds a parameter called name, set with the value photos/primary to the dialog form:

    <cq:formParameters
        jcr:primaryType="nt:unstructured"
        name="photos/primary"/>
        

Les exemples de code sont fournis à titre d’illustration seulement.

cq:inplaceEditing

The cq:inplaceEditing node (node type cq:InplaceEditingConfig) defines an inplace editing configuration for the component. It can have the following properties:

Property Name Property Value
active (boolean) True to enable the inplace editing of the component.
configPath (String) Path of the editor configuration. The configuration can be specified by a configuration node.
editorType

(String) Editor type. The available types are:

  • plaintext: to be used for non HTML content.
  • title: is an enhanced plaintext editor that converts graphical titles into a plaintext before editing begins. Used by the Geometrixx title component.
  • text: to be used for HTML content (uses the Rich Text Editor).

The following configuration enables the inplace editing of the component and defines plaintext as the editor type:

    <cq:inplaceEditing
        jcr:primaryType="cq:InplaceEditingConfig"
        active="{Boolean}true"
        editorType="plaintext"/>
        

Les exemples de code sont fournis à titre d’illustration seulement.

cq:listeners

The cq:listeners node (node type cq:EditListenersConfig) defines what happens before or after an action on the component. It can have the following properties:

Property Name Property Value
Default Value
beforedelete The handler is triggered before the component is removed.
 
beforeedit The handler is triggered before the component is edited.  
beforecopy The handler is triggered before the component is copied.  
beforemove The handler is triggered before the component is moved.  
beforechildinsert The handler is triggered before the component is inserted inside another component (containers only).  
afterdelete The handler is triggered after the component is removed. REFRESH_SELF
afteredit The handler is triggered after the component is edited. REFRESH_SELF
aftercopy The handler is triggered after the component is copied. REFRESH_SELF
afterinsert The handler is triggered after the component is inserted. REFRESH_INSERTED
aftermove The handler is triggered after the component is moved. REFRESH_SELFMOVED
afterchildinsert The handler is triggered after the component is inserted inside another component (containers only).  

Remarque

In the case of nested components there are certain restrictions on actions defined as properties on the cq:listeners node:

  • For nested components, the values of the following properties must be REFRESH_PAGE:
    • aftermove
    • aftercopy 

The event handler can be implemented with a custom implementation. For example:
afteredit = "project.customerAction"
where project.customerAction is a static method.

The following example is equivalent to the REFRESH_INSERTED configuration:
afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

To know the parameters that can be used in the handlers, refer to the before<action> and after<action> events section of the CQ.wcm.EditBar and CQ.wcm.EditRollover widget documentation.

With the following configuration the page is refreshed after the component has been deleted, edited, inserted or moved:

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>
        

Les exemples de code sont fournis à titre d’illustration seulement.

A closer look at a few of the foundation components...

The following sections explain how the most commonly used components of the reference website Geometrixx have been developed.

Top Navigation Component

The Top Navigation Component displays the top level pages of the website. This navigation component is placed at the top of the content pages in the website.

There is no content to be handled by this component. Therefore there is no need for a dialog, only rendering.

Specification summary:

  • /libs/foundation/components/topnav

  • Displays level one pages (below Homepage).

  • Respects On/Off status and uses image rendering.

  • Displays as in the following screenshot:

file

Navigation Essentials

The main function of a navigation component is to:

  • show the hierarchical page structure of a website

  • provide the possibility to access the pages within this structure.

To achieve this, functionality to get the childpages of a specific page is essential. Also required is the functionality to: get the path of the parent page of any page on a specific absolute level (start page of the navigation), check the validity of a page and of course get the path and title of a page.

The following are an introduction to the relevant functionality (API calls):

  • com.day.cq.wcm.core.PageManager.getPage(String path): get the page related to a path

  • com.day.cq.wcm.core.Page.listChildren(): get the childpages of the page

  • com.day.cq.wcm.core.Page.getPath() + .getTitle(): get the path or title of the page respectively

  • com.day.cq.wcm.core.Page.isValid() + .isHideInNav(): checks if the page is valid or the hide in navigation property is set respectively

  • com.day.cq.wcm.core.Page.getAbsoluteParent(int level): Get the parent page on an absolute level

  • PageFilter(): The default AEM Page filter: checks if the page is valid (by checking that the property hideInNav is not set, performing checks on On-/Offtime etc); can be used instead of isValid() and isHideInNav()

For more detailed information please have a look at the Javadoc provided with AEM WCM.

Image Rendering Essentials

To be able to use image based navigation items, a mechanism is needed to request a page in an image navigation item view.

To achieve this a specific selector is added to the request for the navigation item image of a page; for example, /path/to/a/page.navimage.png. Requests with such a selector have to be handled by an image processing mechanism. Sling's request processing mechanism is used for this. To realize this, an image processing script (or servlet) is added, this handles all requests with the specific selector (for example, /contentpage/navimage.png.jsp or /contentpage/navimage.png.java).

For rendering text images the abstract servlet AbstractImageServlet is very helpful. By overwriting the createLayer() method, it is possible to programmatically create a fully customized image.

The following lists the relevant functionalities (API calls):

  • com.day.cq.wcm.commons.AbstractImageServlet

  • com.day.cq.wcm.commons.WCMUtils

  • com.day.cq.wcm.foundation.ImageHelper

  • com.day.image.Font

  • com.day.image.Layer

For more detailed information please have a look at the Javadoc provided with AEM WCM.

Image based Top Navigation Component

The Top Navigation component renders graphical (image based) navigation items.

The images for the navigation items are requested from the page resources in a specific view. This means, the paths of the image tags for the navigation items are equivalent to the paths of the pages that the navigation items represent. To identify the view (kind of presentation) the resource (page) is rendered by, a specific URL selector ('navimage') is added.

List Children Component

The List Children component displays the child pages under a given root page. The root page can be configured for every instance of this component (for every paragraph which is rendered by this component). Therefore a dialog is needed to store the path of the root page as content in the corresponding paragraph resource. If no root page is set, the current page is taken as the root page. The component displays a list of links with title, description and date.

Specification summary:

  • Display a list of links with title, description and date, referring to pages which are below either the current page or a root page defined by the path provided in a dialog

  • /libs/foundation/components/listchildren

  • Respects the On/Off status of displayed pages

  • The following screenshot shows an example of how it displays:

file

Dialog & Widgets

The Dialog of a component is defined in a subtree of nodes below the component's root node. The root node of the dialog is of nodeType cq:Dialog and named dialog. Below this, root nodes for the individual tabs of the dialog are added. These tab nodes are of nodeType cq:WidgetCollection. Below the tab-nodes, the widget nodes are added; these are of nodeType cq:Widget.

Summary:

 

Location: /apps/<myapp>/<mycomponent>/dialog

Root Node:

  • dialog (cq:Dialog) - node for the dialog

Vital Properties:

  • xtype=panel - Defines the dialog's xtype as panel; title sets the title of the dialog

Vital Child Nodes of Dialog Node:

  • items (cq:WidgetCollection) - tab nodes within the dialog

Vital Child Nodes of Tab Node:

  • <mywidget> (cq:Widget) - widget nodes within the tab

Vital Properties:

  • name - Defines the name of the property where the content provided by this widget is stored (usually something like ./mypropertyname)

  • xtype - Defines the widget's xtype

  • fieldLabel - The text displayed in the dialog as a label for this widget

Logo Component

The Logo component displays the logo of the website Geometrixx. The logo image and the home link can be configured globally (same for every page of the website) so that every instance of this component is identical. Therefore a design dialog is needed to provide the image and path of the home link to the design of the corresponding Page. The Logo component is placed in the upper left corner of all pages on the website.

Specification summary:

  • /libs/foundation/components/logo

  • Displays a linked logo image in the upper left corner (spooled image, no rendering)

  • The path for the link is the path of a page on a defined absolute level

  • The logo image and the level are the same for all pages on the website; store the logo image and level in the design of geometrixx

  • Displays as in the following screenshot

file

Designer

The Designer is used to manage the look-and-feel of the global content; including the path to the tool-pages, image of the logo, design values such as text family, size and so on.

Summary:

 

Location: /etc/designs

Root Node:

  • <mydesign> (cq:Page) - Hierarchy node of the design page

Vital Child Nodes:

  • jcr:content (cq:PageContent) - Content node for the design

Vital Properties of Child Node jcr:content:

  • sling:resourceType = “wcm/designer” - Reference to the designer rendering component

The Designer values can be accessed by the currentStyle object provided in global.jsp.

Design dialogs are structured in the same way as normal dialogs but are named design_dialog.

Paragraph System

The Paragraph System is a key part of a website as it manages a list of paragraphs. It is used to structure the individual pieces of content on a website. You can create paragraphs inside the Paragraph System, move, copy and delete paragraphs and also use a column control to structure your content in columns.

The Paragraph System provided in AEM WCM foundations covers most of the variants needed and can also be configured by allowing you to select the components to be activated/deactivated within your current paragraph system.

Inheritance Paragraph System (iparsys)

The inherited paragraph system is a paragraph system that also allows you to inherit the created paragraphs from the parent.You add paragraphs to iparsys (at for example, /content/geometrixx/en/products) and as result, all the subpages of products that also have iparsys with the same name inherit the created paragraphs from the parent. On each level, you can add more paragraphs, which are then inherited by the children pages. You can also cancel paragraph inheritance at a level at any time.

In Design Mode you can configure:

  • Cancel Inheritance
    If selected, the components in this paragraph system are not passed down to the child pages.
  • Disable Inheritance
    If selected, components of this paragraph system on this page are not inherited from the parent page.

parbase

Parbase is a key component as it allows components to inherit attributes from other components, similar to subclasses in object oriented languages such as Java, C++, and so on. For example, when you open the /libs/foundation/components/text node in the CRXDE Lite, you see that it has a property named sling:resourceSuperType, which references the parbase component. The parbase here defines tree scripts to render images, titles, and so on, so that all components subclassed from this parbase can use this script.

Users do not need access to the parbase.

Image Component

The Image component displays images in the main paragraph system.

Specification summary:

  • /libs/foundation/components/image

  • Displays an image in the main paragraph system.

  • The image and certain paragraph-related display properties (title, description, size) are stored in the paragraph resource by a dialog.

  • Some global design properties, valid for all paragraphs of this type (minimal size, maximal size), are stored in the design by a design dialog.

  • There is the possibility to crop, map etc the image.

Widget smartimage

The smartimage widget is an extended widget used to handle the most common aspects of image handling in a WCM system. It controls the upload of the image file and stores the reference to the media library. It also supports the cropping and mapping of images amongst other functions.

The most important properties of the smartimage widget are:

  • xtype - The type of widget ('smartimage').

  • name - The place to store the image file (binary), usually ./image/file or ./file.

  • title - The title displayed in the dialog.

  • cropParameter - The place to store the crop coordinates, usually ./image/imageCrop or ./imageCrop.

  • ddGroups - Groups in contentfinder from where assets can be dragged to this widget.

  • fileNameParameter - Specifies where the name of the image file will be stored, usually ./image/fileName or ./fileName.

  • fileReferenceParameter - Location to store the image reference when an image from the media library is used, usually ./image/fileReference or ./fileReference.

  • mapParameter - Where to store the map data, usually ./image/imageMap or ./imageMap.

  • requestSuffix - The default suffix to be used when browsing for an image with this widget, usually ./image.img.png or ./img.png.

  • rotateParameter - Where to store the rotation specification, usually ./image/imageRotate or ./imageRotate.

  • sizeLimit - Maximum size limit, i.e. 100.

  • uploadUrl - The path to be used when storing data temporarily, usually /tmp/uploaded_test/*.

Contentfinder Essentials

To be able to drag assets from the contentfinder to a component there must be a drop target configuration node called cq_dropTargets below the edit configuration node (cq:editConfig).

Summary:

Location: /apps/<myapp>/components/<mycomponent>/cq:editConfig/cq:dropTargets

Root node:

  • cq:dropTargets (cq:DropTargetConfig) - Hierarchy Node of the drop target configuration.

Below this node the following node tree (with vital properties) must be created for the smartimage:

  • image (nt:unstructured) with the following vital properties:

    • accept - The media types to be accepted; i.e. image/gif, image/jpeg or image/png.

    • groups - Groups in the contentfinder from where assets can be accepted, i.e. media

    • propertyName - Where the reference will be stored; usually ./image/fileReference or ./fileReference

In the case that the image is stored in a separate image node in the content (for example, as with textimage, when the image is not the only data to be stored for the resource) the following two nodes must also be created:

  • parameters (nt:unstructured) below the image node

  • image (nt:unstructured) below the parameters node with the following vital properties:

    • sling:resourceType - The resource type to be stored in the case that a complete paragraph has to be created (as when dragging an asset to the paragraphsystem while pressing the Alt button).

Image Component Essentials

This section lists the most relevant functionalities (API calls) for the programmatic manipulation of images:

  • com.day.cq.wcm.foundation.Image

    • addCssClass

    • loadStyleData

    • setSelector

    • setSuffix

    • draw

    • getDescription

  • com.day.cq.wcm.api.components.DropTarget

  • com.day.cq.wcm.api.components.EditConfig

  • com.day.cq.wcm.commons.WCMUtils

For more detailed information please look at the Javadoc provided with AEM WCM.

Image Rendering Essentials

As for the Top Navigation component, the AbstractImageServlet is used to render the images. For an introduction to the AbstractImageServlet, see the Image Rendering Essentials in the Top Navigation Component section.

As the request to the resource in the 'image view' has to be detected, a specific selector to the request of the image (i.e. /path/to/the/resource.img.png) needs to be added. Requests with such a selector are handled by the image processing servlet.

Text Image Component

The Text Image Component displays text and images in the main paragraph system.

Specification summary:

  • /libs/foundation/components/textimage
  • Displays a text and image in the main paragraph system.
  • The text and image together with specific paragraph related display properties (title, description, size) are stored in the paragraph resource (dialog).
  • There is the possibility to manipulate the image, including cropping and mapping amongst other functions.
  • For the image rendering use the servlet created for the image component (to inherit from the image component set resourceSuperType)
  • Text input uses the Rich Text Editor, which can be fully configured.
  • On the Advanced Image Properties tab the Style can be configured to list styles defined in your CSS file. Often these are used to left or right align the image.

Widget richtext

The richtext widget is an extended widget used to handle the most common aspects of text handling in a WCM system. It stores the text with the formatting information.

The most important properties of the richtext widget are:

  • xtype - The type of the widget ('richtext')

  • name - Where the text is stored, usually ./text.

  • hideLabel - Defines whether the label should be displayed, usually false.

  • richFlag (xtype=hidden) with name ./textIsRich, ignoreData=true and value=true - Used to define that format is rich text format.

Text & Image Component Essentials

This section lists the most relevant functionalities (API calls) for the programmatic manipulation of texts and images:

  • com.day.cq.wcm.foundation.TextFormat

  • com.day.cq.wcm.api.WCMMode

For more detailed information please have a look at the Javadoc provided with AEM WCM.

Search Component

The Search component can be placed in the paragraph system of any page. It searches the content of the site for a query provided in the request.

Specification summary:

  • /libs/foundation/components/search

  • Displays a search form.

  • Displays the result of the search for a query provided in the request (if a query was provided).

  • Provides a dialog to define some properties

    • Search button text

    • No results text

    • Previous label

    • Next label

  • Provides pagination

Search Essentials

This section lists the most relevant functionalities (API calls) for the programmatic manipulation of searches:

  • com.day.cq.wcm.foundation.Search - Search Class to be used for almost every aspect of the search. The query is expected in a request parameter named 'q'

    • getResult - Get the result object

  • com.day.cq.wcm.foundation.Search.Result

    • getResultPages

    • getPreviousPage

    • getNextPage

For more detailed information please have a look at the API documentation provided with AEM WCM.

​