AEM Components: Basics (2023)

When you start developing new components, you need to understand the basics of their structure and configuration.

This process involves reading the theory and looking at the wide range of component implementations in a standard AEM instance. This latter approach is somewhat complicated by the fact that while AEM has moved to a new standardized modern touch UI, it still supports the classic UI.

general description

This section covers key concepts and issues as an introduction to the details required when developing your own components.

planning

Before you start configuring or coding your component, you should ask yourself:

• What exactly should the new component be able to do?

  • A clear specification helps in all phases of development, testing and delivery.

    Details may change over time, but the specification may be updated (although changes must also be documented).

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

  • The wheel does not have to be reinvented.
  • There are several mechanisms provided by AEM to allow you to inherit and extend details from another component definition including overriding, overlaying andFusion of Sling resources.

• Does your component need logic to select/manipulate the content?

  • The logic should be kept separate from the UI layer. HTL aims to help ensure this happens.

• Does your component require CSS formatting?

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

• Which security aspects should I consider?

  • VerSecurity Checklist: Best Development Practicesfor more details.

Tactile vs. classic user interface

Before starting a serious discussion about component development, you need to know what UI your authors will use:

• Touch user interface
  The default user interfacewhich was previewed in AEM 5.6.0 and enhanced in 6.x. It is built on the unified user experience for Adobe Marketing Cloud and uses the underlying technologies ofCoral UIjGranite user interface.

• classic user interface
  User interface based on ExtJS technology introduced with CQ 5.1.

VerUser interface recommendations for customersfor more details.

Components can be implemented to support Touch UI, Classic UI, or both. If you look at a default instance, you'll also see out-of-the-box components originally designed for classic UI, touch UI, or both.

For that reason, on this page we cover the basics of both and how to spot them.

Content logic and rendering markup

It is recommended to keep the code responsible for markup and rendering separate from the code that controls the logic used to select the content of the component.

This philosophy is supported byHTL, a templating language intentionally constrained to ensure that an actual programming language is used to define the underlying business logic. This (optional) logic is invoked by HTL with a specific command. This mechanism highlights the code being called for a specific view and allows specific logic for different views of the same component if needed.

HTL frente a JSP

HTL is an HTML template language introduced with AEM 6.0.

Discussion of useHTLo JSP (Java Server Pages) when developing your own components should be easy as HTL is now the recommended scripting language for AEM.

Both HTL and JSP can be used to develop components for both classic and touch UI. Although there is a tendency to assume that HTL is only for touch UI and JSP for classic UI, this is a mistake and more due to timing. Touch UI and HTL were introduced to AEM around the same time. Since HTL is now the recommended language, it will be used for new components that are more intended for touch UI.

Develop your own components

To create your own components for the right UI see (after reading this page):

• AEM components for touch UI
• AEM components for the classic UI

A quick start is to copy an existing component and then make the changes you want. To learn how to create your own components and add them to the paragraph system, see:

• components under development(Focus on Touch UI)

Move components to the publish instance

The components that render the content must be deployed on the same AEM instance as the content. Therefore, all components used to create and render pages in the Author instance must be implemented in the Publish instance. When implemented, components are available to render enabled pages.

Use the following tools to push your components into the publish instance:

• Use the package managerto add your components to a package and move them to another AEM instance.
• Use the Activate Tree Replication Toolto replicate the components.

Components to consider from the start

• book page:

  • AEM hat diebook pageComponents (cq:page).
  • This is a specific type of resource that is important for content management.
    • A page is a web page that contains content for your website.

• Paragraph systems:

  • The paragraph system is an important part of a website as it maintains a list of paragraphs. It serves to accommodate and structure the individual components that contain the actual content.
  • In the paragraph system, you can create, move, copy, and delete paragraphs.
  • You can also select the components that are available for use in a specific paragraph system.
  • Several paragraph systems are available within a standard instance (e.gpresses,[Responsive Grid](/docs/experience-manager-64/sites-authoring/responsive-layout.md)).

Structure

The structure of an AEM component is powerful and flexible, the main considerations are:

• resource type
• component definition
• Properties and child nodes of a component
• dialogues
• Shaping dialogues
• component availability
• Components and the content they create

resource type

A key element of the structure is the resource type.

• The structure of the content explains intentions.
• resource type implement them.

This is an abstraction that helps ensure intent is maintained even if appearance changes over time.

component definition

Component Basics

The definition of a component can be broken down as follows:

• AEM components are based onHonda.

• AEM components are (usually) located in:

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

• Project/site specific components are (usually) located in:

  • /applications/<myApplication>/components

• AEM standard components are defined ascq:componentand have the most important elements:

  • jcr properties:

    A list of jcr properties; these are variables and some may be optional, although the basic structure of a component node, its properties and subnodes are defined by thecq:componentDefinition

  • Resources:

    These define the static elements used by the component.

  • Hyphens:

    (Video) AEM Beginner #11 | What is AEM Component

  They are used to implement the behavior of the resulting instance of the component.

• root node:

  • <micomponent> (cq:component)- Component hierarchy node.

• Vital Properties:

  • jcr:title- component title; For example, it is used as a tag when viewing the component in the component browser or plugin.

  • jcr: description- description of the component; can be used as a hover hint in the component or companion browser.

  • classic user interface:

    • icono.png- Icon for this component.
    • thumbnail.png- Image is displayed when this component is listed in the paragraph system.

  • Touch IE

    • see sectionComponent icon on touch UIfor details.

• vital child nodes:

  • cq:editConfig (cq:EditConfig)- Defines the editing properties of the component and allows the component to be viewed in the component browser or sidekick.

    Note: If the component has a dialog box, it will automatically appear in the component browser or sidekick even if cq:editConfig is not present.

  • cq:childEditConfig (cq:EditConfig)- Controls author UI aspects for child components that don't define their owncq:editConfig.

  • Touch UI:

    • cq:dialog(nt: unstructured) - dialog for this component. Defines the interface that allows the user to configure the component and/or edit content.
    • cq:layout_dialog(nt: unstructured) - Layout editing for this component

  • classic user interface:

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

Component icon on touch UI

The component's icon or abbreviation is defined by the component's JCR properties when the developer creates the component. These properties are evaluated in the following order, and the first valid property found is used.

1. cq:Symbol- String property that points to a default symbol on theCoral UI librarydisplayed in the component browser

   • Use the value of the coral icon's HTML attribute.

2. abbreviation- String property to customize abbreviation of component names in component browser

   • The abbreviation must be limited to two characters.

   • If you specify an empty string, the abbreviation is created from the first two characters of thejcr:titleProperty.

     • Example: "I am" for "image"
     • The localized title is used to form the abbreviation.

   • The abbreviation is only translated if the component has aabbreviation_comment I18nproperty, which is then used as a translation hint.

3. cq:icono.pngÖcq:icono.svg- Icon for this component that is displayed in the component browser

   • 20x20 pixels is the size of the default component icons.

     • Larger icons are scaled down (client side).

   • The recommended color is rgb(112, 112, 112) > #707070

   • The background of the icons of the standard components is transparent.

   • Solo.pngj.svgThe files are supported.

   • When importing from the file system via the Eclipse plugin, the filenames must be escaped_cq_icono.pngÖ_cq_icono.svgFor example.

   • .pnghas priority.svgif both are present

If none of the above properties (cq:Symbol,abbreviation,cq:icono.pngÖcq:icono.svg) are in the component:

• The system looks for the same properties in the supercomponents that follow itloop:resourceSuperTypeProperty.
• If nothing or an empty abbreviation is found at the super component level, the system builds the abbreviation from the first letters of thejcr:titleProperty of the current component.

To cancel symbol inheritance for supercomponents, set voidabbreviation-property of component reverts to default behavior.

Iscomponent consoleshows how the symbol is defined for a specific component.

Example of an SVG icon

<?xml versión="1.0" codificación="utf-8"?><!DOCTYPE svg PÚBLICO "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG /1.1/DTD/svg11.dtd"><svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www. w3.org/1999/xlink" x="0px" y="0px" width="20px" height="20px" viewBox="0 0 20 20" enable-background="nuevo 0 0 20 20" xml:espacio ="preservar"> <elipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/> <elipse cx="15" cy="5" rx=" 4" ry="4" fill="#707070"/> <elipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/> <elipse cx=" 15" cy="15" rx="4" ry="4" fill="#707070"/></svg>

Properties and child nodes of a component

Many of the nodes/properties required to define a component are common to both UIs, and the differences remain independent, allowing your component to work in either environment.

A component is a type nodecq:componentand has the following properties and child nodes:

Let's look at thoseTextcomponent (any version), we can see these elements:

• HTML (/libs/wcm/foundation/components/text)

  

• JSP (/libs/foundation/components/text)

  

Properties of particular interest are:

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

• jcr: description- description of the component; can be used as a hover hint in the component list in the sidekick

• loop:resourceSuperType: This specifies the inheritance path when a component is extended (by overriding a definition)

Child nodes of particular interest include:

• cq:editConfig(cq:EditConfig) - this controls the visual aspects; For example, you can define the appearance of a bar or widget, or add custom controls

• cq:childEditConfig(cq:EditConfig) - this controls the visual aspects of child components that do not have their own definitions

• Touch UI:

  • cq:dialog(nt: unstructured) - defines the dialog for editing the content of this component
  • cq:layout_dialog(nt: unstructured) - sets layout editing options for this component

• classic user interface:

  • Dialog(cq: Dialog): defines the dialog for editing the content of this component (specific to the classic UI)
  • design_dialog(cq: Dialog) - sets layout editing options for this component
  • icono.png- Graphic file to use as icon for the component on the sidekick
  • thumbnail.png- Graphics file to use as the thumbnail for the component when dragging from the sidekick

dialogues

Dialogs are a key element of your component as they provide an interface for authors to configure and provide information 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.

Dialog definitions are user interface specific:

• Touch user interface

  • cq:dialog(nt: unstructured) nodes:

    • Define the dialog for editing the content of this component

    • specific to touch UI

    • are defined by the Granite user interface components

    • own propertySnare: Resource type, as the default Sling content structure

    • can have a propertyauxiliary pathto define the context-sensitive help resource (absolute or relative path) that is accessed when the help icon (the ? symbol) is selected.

      • For prebuilt components, this often links to a page in the documentation.
      • Butauxiliary pathis specified, the default URL (documentation overview page) is displayed.

  

  Individual fields are defined within the dialog:

  

• classic user interface

  • Dialog(cq: Dialog) node

    • Define the dialog for editing the content of this component

    • specific to the classic UI

    • define themselves with ExtJS widgets

    • own propertyxtipo, which refers to ExtJS

    • can have a propertyauxiliary pathto define the context-sensitive help resource (absolute or relative path) accessed whenHelpbutton is selected.

      • For prebuilt components, this often links to a page in the documentation.
      • Butauxiliary pathis specified, the default URL (documentation overview page) is displayed.

  

  Individual fields are defined within the dialog:

  

  In a classic dialogue:

  • You can create the dialog likecq: Dialog, which provides a single tab, as in the text component, or if you need multiple tabs, as in the text-image component, the dialog can be defined ascq:Tab-Panel.
  • Acq:widget collection(elements) is used to provide a base for input fields (cq: Widget) or additional tabs (cq: Widget). This hierarchy can be extended.

Shaping dialogues

Layout dialogs are very similar to dialogs for editing and configuring content, but provide authors with the interface to configure and provide layout details for that component.

Draft dialogs are available in draft mode, although they are not required for all components, e.g.titlejBildboth have layout dialogs whileTextit is not.

The layout dialog for the paragraph system (e.g. parsys) is a special case as it allows the user to specify other components to be available for selection (from the component browser or wizard) on the page.

Add your component to the paragraph system

Once a component has been defined, it must be available for use. To make a component available for use in a paragraph system, you can:

1. OpenDesignmodusfor a page and activate the required component.

2. Add the required componentscomponentsproperty of your template definition to:

   /etc/designs/<*suProyecto*>/jcr:content/<*suPlantilla*>/par

   See for example:

   /etc/designs/geometrixx/jcr:content/contentpage/par

   

Components and the content they create

If we have an instance of thetitleComponent on the side:<Content Path>/Prototype.html

• Touch user interface

  

• classic user interface

  

Then we can see the structure of the content created in the repository:

Especially if you look at the actual text of atitle:

• the definition (for both UIs) has the propertyName=./jcr:title

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

• within the content, this generates the propertyjcr:titleRetention of the author's content.

The properties defined depend on the individual definitions. Although they can be more complex than the above, they still follow the same basic principles.

Component Hierarchy and Inheritance

Components within AEM follow 3 different hierarchies:

• Resource Type Hierarchy

  This is used to extend components using the propertyloop:resourceSuperType. This allows the component to inherit. For example, a text component inherits several attributes from the standard component.

  • Scripts (solved by Sling)
  • dialogues
  • Descriptions (including thumbnails, icons, etc.)

• Containerhierarchie

  This is used to complete the configuration settings in the child component and is most commonly used in a Parsys scenario.

  For example, configuration settings for formula bar buttons, control set layout (formula, rollover), and dialog layout (inline, float) can be defined in the parent component and propagated to child components.

  Configuration settings (related to editing functions) incq:editConfigjcq:childEditConfigthey spread.

  (Video) AEM Page Authoring & Component Development

• include hierarchy

  This is enforced at runtime by the include sequence.

  This hierarchy is used by the designer, which in turn serves as the basis for various design aspects of the presentation; including layout information, CSS information, the components available in a parsys, among others.

edit behavior

This section explains how to configure the editing behavior of a component. This includes attributes such as actions available on the component, direct editor capabilities, and listeners related to events in the component.

Settings are the same for both Touch and Classic UI, albeit with some specific differences.

A component's editing behavior is configured by adding acq:editConfigEnter nodecq:EditConfigbelow the component node (of typecq:component) and 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:design(Chain): - Defines how the component is edited in the classic UI.

  • cq: Dialogmodus(Chain): defines how the component dialog is opened in the classic UI

    • In Touch UI, dialogs always float in desktop mode and automatically open in full screen on mobile.

  • cq: write SMS(Chain): Defines the text that is displayed when there is no visual content.

  • cq:heredar(boolesch): Defines whether missing values ​​are inherited from the component they inherit from.

  • Dialogdesign(String): Defines how the dialog should be opened.

• cq:editConfig child nodes:

  • cq:dropTargets(node ​​typent: unstructured): defines a list of drop targets that can accept a drop from a content engine asset

    • Some placement targets are only available in the classic interface.
    • Only one drop target is allowed in the touch UI.

  • cq:actionConfigs(node ​​typent: unstructured): defines a list of new actions to be added to the cq:actions list.

  • cq:formParameter(node ​​typent: unstructured): defines additional parameters that are added to the dialog form.

  • cq:inplaceEditing(node ​​typecq:InplaceEditingConfig): Defines an in-place editing configuration for the component.

  • cq: listener(node ​​typecq:EditListenersConfig): Defines what happens before or after an action is performed on the component.

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" cq:actions="[ editar]" cq:dialogMode="floating" cq:layout="editbar" jcr:primaryType="cq:EditConfig"> <cq:oyentes jcr:primaryType="cq:EditListenersConfig" afteredit="REFRESH_PAGE"/></jcr :raíz>

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

• To look for a propertycq:editConfignode, p.cq:Actions, you can use the query tool atCRXDE Liteand search using the following XPath query string:

  //element(cq:editConfig, cq:EditConfig)[@cq:actions]

• To find a child node ofcq:editConfig, e.g. you can searchcq:dropTargets, which is of typecq:DropTargetConfig; You can use the query tool in **CRXDE Lite** and search with the following XPath query string:

  //elemento(cq:dropTargets, cq:DropTargetConfig)

component placeholder

Components must always render some HTML visible to the author, even if the component has no content. Otherwise, it could visually disappear from the editor interface, making it technically present but invisible on the page and in the editor. In such a case, authors cannot select and interact with the empty component.

Because of this, components should display a placeholder whenever they don't display visible output when the page is viewed in the page editor (when WCM mode is enabled).EditÖAdvance payment).
Typical HTML markup for a placeholder looks like this:

<div class="cq-placeholder" data-emptytext="Komponentenname"></div>

The typical HTL script that renders the HTML placeholder above is as follows:

<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}" data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}">< /div>

In the example aboveit is emptyis a variable that is only true if the component has no content and is invisible to the author.

To avoid duplication, Adobe recommends component implementers to use an HTL template for these placeholders.as provided by the main components.

The template in the link above is then used with the following HTL line:

<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html" data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly >

In the example abovetemplate.textis the variable that is only true if the content has content and is visible.

For an example of using this template, see the main components,as in the title component.

Configuration with cq:EditConfig Properties

cq:Actions

Iscq:ActionsProperty (String-Array) defines one or more actions that can be performed on the component. The following values ​​are available for configuration:

The following configuration adds an edit button, spacer, delete button, and paste button to the component's formula bar:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" cq:actions="[ editar,-,eliminar,insertar]" cq:layout="barra de edición" jcr:primaryType="cq:EditConfig"/>

The following setting adds the text "Settings inherited from base framework" to the component's formula bar:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" cq:actions="[ text:Configuraciones heredadas del marco base]" cq:layout="editbar" jcr:primaryType="cq:EditConfig"/>

cq:layout (classic IU only)

Iscq:designProperty (Chain) defines how the component can be edited in the classic UI. The following values ​​are available:

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

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" cq:actions="[ editar]" cq:layout="barra de edición" jcr:primaryType="cq:EditConfig"></jcr:root>

cq:dialogMode (classic UI only)

The component can be linked to an editing dialog. Hecq: DialogmodusProperty (Chain) defines how the component's dialog opens in the classic UI. The following values ​​are available:

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

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" cq:actions="[ editar]" cq:dialogMode="flotante" cq:layout="barra de edición" jcr:primaryType="cq:EditConfig"></jcr:root>

cq: write SMS

Iscq: write SMSProperty (Chain) defines the text that is displayed when there is no visual content. By default it is:Drag components or assets here.

cq:heredar

Iscq:heredarProperty (boolesch) defines whether missing values ​​are inherited from the component they inherit from. default isINCORRECT.

Dialogdesign

IsDialogdesignThe property defines how a dialog should be opened by default.

• a value offull screenopens the dialog in full screen mode.
• An empty value or the absence of the default property opens the dialog normally.
• Note that the user can toggle full screen mode within the dialog at any time.
• It does not apply to the classic UI.

Configuration with cq:EditConfig child nodes

cq:dropTargets

Iscq:dropTargetsnode (node ​​typent: unstructured) defines a list of drop targets that can accept dropping an asset dragged from the content browser. Serves as a collection of type nodescq:DropTargetConfig.

Any child node of the typecq:DropTargetConfigdefines a drop target on the component. The node name is important because it must be used in the JSP to generate the name of the CSS class assigned to the DOM element that is the effective drop target, as follows:

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

Is<*drag-and-drop prefix*>is defined by the Java property:

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

For example, in the download component JSP, the class name is defined as follows
(/libs/fundación/componentes/descarga/descarga.jsp), Woarchiveis the node name of the drop target in the edit configuration of the download component:

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "archivo";

The type nodecq:DropTargetConfigmust have the following properties:

The following configuration is from the download component. Activates each asset (MIME type can be any string) from themedia-Group to drop into the component from the content browser. After the crash, the property of the componentFile numberIt is updated:

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

cq:actionConfigs (classic UI only)

Iscq:actionConfigsnode (node ​​typent: unstructured) defines a list of new actions to add to the list defined bycq:ActionsProperty. Each child node ofcq:actionConfigsdefines a new action by defining a widget.

The following sample configuration defines a new button (with a delimiter for the classic UI):

• a delimiter defined by type xtb separator;

  • This is only used by the classic UI.
  • The Touch UI ignores this definition because x-types are ignored (and the delimiters are not needed since the action toolbar is structured differently in the Touch UI).

• a button calledManage Commentswhich performs the controller functionCQ_collab_forum_openCollabAdmin().

<jcr:raíz xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https ://www.jcp.org/jcr/nt/1.0" cq:actions="[EDITAR,COPIAR,MOVER,ELIMINAR,INSERTAR]" jcr:primaryType="cq:EditConfig"> <cq:actionConfigs jcr:primaryType= "nt :sin estructurar"> <separator0 jcr:primaryType="nt:sin estructurar" xtype="tbseparator"/> <manage jcr:primaryType="nt:unstructured" handler="function(){CQ_collab_forum_openCollabAdmin();}" text="Kommentare verwalten"/> </cq:actionConfigs></jcr:root>

cq:formParameter

Iscq:formParameternode (node ​​typent: 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 calledName, set with valuephotos/primaryto the dialogue form:

<cq:formParameters jcr:primaryType="nt:unstructured" name="fotos/principal"/>

cq:inplaceEditing

Iscq:inplaceEditingnode (node ​​typecq:InplaceEditingConfig) defines an in-place editing configuration for the component. It can have the following properties:

The following configuration allows direct editing of the component and definesplain textas editor type:

<cq:InplaceEditing jcr:primaryType="cq:InplaceEditingConfig" active="{Boolean}true" editorType="texto sin formato"/>

cq: listener

Iscq: listenernode (node ​​typecq:EditListenersConfig) defines what happens before or after an action on the component. The following table defines its possible properties.

The event handler can be implemented with a custom implementation. For example (whereproject.customer actionis a static method):

afteredit = "project.clientAction"

The following example is equivalent toREFRESH_INSERTEDAttitude:

afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

With the following configuration, the page is refreshed after the component is removed, edited, inserted, or moved:

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