AEM Components - The Basics aem-components-the-basics

What exactly do you need the new component to do?

• A clear specification helps at all stages of development, testing and handover.

  Details may change over time, but the specification can be updated (though changes should be documented too).

Do you need to create your component from scratch, or can you inherit the basics from an existing component?

• There is no need to reinvent the wheel.
• There are several mechanisms provided by AEM to allow you to inherit and extend details from another component definition including override, overlay, and the Sling Resource Merger.

Will your component require logic to select/manipulate the content?

• Logic should be kept separate from the user interface layer. HTL is designed to help ensure this happens.

Will your component need CSS formatting?

• CSS formatting should be kept separate from the component definitions. Define conventions for naming your HTML elements so that you can modify them through external CSS files.

What security aspects should I take into consideration?

• See Security Checklist - Development Best Practices for further details.

Touch-Enabled UI
The standard user interface that was introduced in AEM 5.6.0 as a preview and extended in 6.x. It is based on the unified user experience for the Adobe Marketing Cloud, using the underlying technologies of Coral UI and Granite UI.

Classic UI
User interface based on ExtJS technology that was introduced with CQ 5.1.

Page:

• AEM has the page component ( cq:Page).
• This is a specific type of resource that is important for content management.
  • A page corresponds to a web page holding content for your website.

Paragraph systems:

• The paragraph system is a key part of a website as it manages a list of paragraphs. It is used to hold and structure the individual components that hold the actual content.
• You can create, move, copy, and delete paragraphs in the paragraph system.
• You can also select the components to be available for use within a specific paragraph system.
• There are various paragraph systems available within a standard instance (for example parsys, [responsivegrid](/docs/experience-manager-64/sites-authoring/responsive-layout.md)).

AEM components are based on Sling.

AEM components are (usually) located under:

• HTL: /libs/wcm/foundation/components
• JSP: /libs/foundation/components

Project/Site specific components are (usually) located under:

• /apps/<myApp>/components

AEM standard components are defined as cq:Component and have the key elements:

• jcr properties:

  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

• Resources:

  These define static elements used by the component.

• Scripts:

Are used to implement the behavior of the resulting instance of the component.

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 in the components browser or sidekick.

• jcr:description - Description for the component; can be used as mouse-over hint in the components browser or sidekick.

• Classic UI:

  • icon.png - Icon for this component.
  • thumbnail.png - Image shown if this component is listed within the paragraph system.

• Touch UI

  • See the section Component Icon in Touch UI for details.

Vital Child Nodes:

• cq:editConfig (cq:EditConfig) - Defines the edit properties of the component and enables the component to appear in the Components browser or Sidekick.

  Note: if the component has a dialog, it will automatically appear in the Components browser or Sidekick, even if the cq:editConfig does not exist.

• cq:childEditConfig (cq:EditConfig) - Controls author UI aspects for child components that do not define their own cq:editConfig.

• Touch-Enabled UI:

  • cq:dialog ( nt:unstructured) - Dialog for this component. Defines the interface allowing the user to configure the component and/or edit content.
  • cq:design_dialog ( nt:unstructured) - Design editing for this component

• Classic UI:

  • dialog ( cq:Dialog) - Dialog for this component. Defines the interface allowing the user to configure the component and/or edit content.
  • design_dialog ( cq:Dialog) - Design editing for this component.

HTL ( /libs/wcm/foundation/components/text)

JSP ( /libs/foundation/components/text)

jcr:title - title of the component; this can be used to identify the component, for example, it appears in the component list within the components browser or sidekick

jcr:description - description for the component; can be used as mouse-over hint in the component list within sidekick

sling:resourceSuperType: this indicates the path of inheritance when extending a component (by overriding a definition)

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

Touch-Enabled UI:

• cq:dialog ( nt:unstructured) - defines the dialog for editing content of this component
• cq:design_dialog ( nt:unstructured) - specifies the design editing options for this component

Classic UI:

• dialog ( cq:Dialog) - defines the dialog for editing content of this component (specific to the classic UI)
• design_dialog ( cq:Dialog) - specifies the design editing options for this component
• icon.png - graphics file to be used as an icon for the component in the Sidekick
• thumbnail.png - graphics file to be used as a thumbnail for the component while dragging it from the Sidekick

Touch-Enabled UI

• cq:dialog ( nt:unstructured) nodes:

  • define the dialog for editing content of this component

  • specific to the touch-enabled UI

  • are defined using Granite UI components

  • have a property sling:resourceType, as standard Sling content structure

  • can have a property helpPath to define the context sensitive help resource (absolute or relative path) that is accessed when the Help icon (the ? icon) is selected.

    • For out-of-the box components this often references a page in the documentation.
    • If no helpPath is specified, the default URL (documentation overview page) is shown.

Within the dialog, individual fields are defined:

Classic UI

• dialog ( cq:Dialog) nodes

  • define the dialog for editing content of this component

  • specific to the classic UI

  • are defined using ExtJS widgets

  • have a property xtype, which refers to ExtJS

  • can have a property helpPath to define the context sensitive help resource (absolute or relative path) that is accessed when the Help button is selected.

    • For out-of-the box components this often references a page in the documentation.
    • If no helpPath is specified, the default URL (documentation overview page) is shown.

Within the dialog, individual fields are defined:

Within a classic dialog box:

• you can create the dialog as cq:Dialog, which will provide a single tab - as in the text component, or if you need multiple tabs, as with the textimage component, the dialog can be defined as cq:TabPanel.
• 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.

Touch-Enabled UI

Classic UI

the definition (for both UIs) have the property name= ./jcr:title

• /libs/foundation/components/title/cq:dialog/content/items/column/items/title
• /libs/foundation/components/title/dialog/items/title

within the content, this generates the property jcr:title holding the author’s content.

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.

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 in the classic UI.

• cq:dialogMode ( String): defines how the component dialog is opened in the classic UI

  • In the touch-enabled UI, dialogs are always floating in desktop mode, and automatically opened as fullscreen in mobile.

• 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.

• dialogLayout (String): defines how the dialog should open.

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

  • Multiple drop targets are only available in the classic UI.
  • In the touch-enabled UI a single drop target is allowed.

• 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.

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. you can search for 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)

a separator, defined by the xtype tbseparator;

• This is only used by the classic UI.
• This definition is ignored by the touch-enabled UI as xtypes are ignored (and separators are unnecessary as the action toolbar is constructed differently in the touch-enabled UI).

a button named Manage comments that runs the handler function CQ_collab_forum_openCollabAdmin().