Komponenten-Referenzhandbuch components-reference-guide

Komponenten bilden den Kern bei der Erstellung eines Erlebnisses in AEM. Die Kernkomponenten und der AEM-Projektarchetyp erleichtern den Einstieg mit einem Toolset aus vorgefertigten, robusten Komponenten. Das WKND-Tutorial führt Entwicklerinnen und Entwickler durch die Verwendung dieser Tools und das Erstellen benutzerdefinierter Komponenten, um eine neue AEM-Site zu erstellen.

Da das WKND-Tutorial die meisten Anwendungsfälle abdeckt, ist dieses Dokument nur als Ergänzung zu diesen Ressourcen gedacht. Es enthält ausführliche technische Details zur Struktur und Konfiguration von Komponenten in AEM und ist nicht als Anleitung für die ersten Schritte gedacht.

Überblick overview

In diesem Abschnitt werden zentrale Konzepte und Schwierigkeiten erläutert. Er bietet so einen guten Einstieg in die Entwicklung eigener Komponenten.

Planung planning

Vor dem Konfigurieren bzw. Programmieren einer Komponente sollten Sie die folgenden Fragen beantworten:

Wiederverwenden vorhandener Komponenten reusing-components

Bevor Sie Zeit in die Erstellung einer völlig neuen Komponente investieren, sollten Sie die Anpassung oder Erweiterung vorhandener Komponenten in Erwägung ziehen. Die Kernkomponenten bieten eine Reihe flexibler, robuster und bewährter produktionstauglicher Komponenten.

Erweitern der Kernkomponenten extending-core-components

Die Kernkomponenten bieten auch klare Anpassungsmuster, die Sie verwenden können, um sie an die Bedürfnisse Ihres eigenen Projekts anzupassen.

Überlagern von Komponenten overlying-components

Komponenten können mit einer Überlagerung ebenfalls neu definiert werden, die auf der Suchpfadlogik basiert. In diesem Fall wird der Sling Resource Merger nicht ausgelöst und /apps muss die gesamte Überlagerung definieren.

Erweitern von Komponentendialogen extending-component-dialogs

Es ist auch möglich, ein Komponentendialogfeld mithilfe des Sling Resource Mergers zu überschreiben und die Eigenschaft sling:resourceSuperType zu definieren.

Dies bedeutet, dass Sie nur die erforderlichen Unterschiede neu definieren müssen, anstatt das gesamte Dialogfeld neu zu definieren.

Inhaltslogik und Rendering-Markup content-logic-and-rendering-markup

Ihre Komponente wird mit HTML gerendert. Ihre Komponente muss den HTML-Code definieren, der notwendig ist, um den erforderlichen Inhalt zu übernehmen und anschließend in der Autoren- und Veröffentlichungsumgebung nach Bedarf zu rendern.

Es empfiehlt sich, den für Markup und Rendering zuständigen Code getrennt von dem Code zu halten, der die Logik zur Auswahl des Komponenteninhalts enthält.

Dieser Ansatz wird durch HTL unterstützt, eine Vorlagensprache, die dazu dient sicherzustellen, dass eine echte Programmiersprache für die Definition der zugrunde liegenden Geschäftslogik genutzt wird. Dieser Mechanismus hebt den Code hervor, der für eine bestimmte Ansicht aufgerufen wird, und lässt bei Bedarf eine spezifische Logik für unterschiedliche Ansichten derselben Komponente zu.

Diese (optionale) Logik kann auf verschiedene Arten implementiert werden und wird von HTL mit bestimmten Befehlen aufgerufen:

Komponentenstruktur structure

Die Struktur einer AEM-Komponente ist leistungsstark und flexibel. Die Hauptbestandteile sind:

Ressourcentyp resource-type

Ein zentrales Element der Struktur ist der Ressourcentyp.

Dies ist eine Abstraktion, die sicherstellen soll, dass die Absicht unverändert bleibt, auch wenn sich das Erscheinungsbild ändert.

Komponentendefinition component-definition

Die Definition einer Komponente lässt sich wie folgt aufschlüsseln:

Wichtige Eigenschaften vital-properties

Komponentensymbol component-icon

Das Symbol oder die Abkürzung für die Komponente wird mit JCR-Eigenschaften der Komponente definiert, wenn die Komponente vom Entwickler erstellt wird. Diese Eigenschaften werden in der folgenden Reihenfolge ausgewertet und die erste erkannte gültige Eigenschaft wird verwendet.

Wenn keine der o. g. Eigenschaften (cq:icon, abbreviation, cq:icon.png oder cq:icon.svg) bei der Komponente gefunden wird:

Um die Vererbung von Symbolen von übergeordneten Komponenten zu deaktivieren, legen Sie eine leere Eigenschaft abbreviation für die Komponente fest. Das Standardverhalten wird daraufhin erneut aktiviert.

Die Komponentenkonsole zeigt an, wie das Symbol für eine bestimmte Komponente definiert ist.

Beispiel: SVG-Symbol svg-icon-example

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//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="new 0 0 20 20" xml:space="preserve">
    <ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
    <ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
    <ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
    <ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>

Eigenschaften und untergeordnete Knoten einer Komponente properties-and-child-nodes-of-a-component

Viele der Knoten/Eigenschaften, die für die Definition einer Komponente erforderlich sind, sind in beiden Benutzeroberflächen zu finden. Die Unterschiede bleiben unabhängig, sodass Ihre Komponente in beiden Umgebungen funktioniert.

Eine Komponente ist ein Knoten des Typs cq:Component mit den folgenden Eigenschaften und untergeordneten Knoten:

In der Textkomponente finden sich die folgenden Elemente:

Zu den wichtigen Eigenschaften gehören:

Zu den wichtigen untergeordneten Knoten gehören:

Dialogfelder dialogs

Dialogfelder sind ein wichtiges Element einer Komponente: Sie stellen den Autoren eine Oberfläche für die Konfiguration der Komponente auf einer Inhaltsseite und für Eingaben für diese Komponente bereit. Weitere Informationen zur Interaktion von Inhaltsautoren mit Komponenten finden Sie in der Authoring-Dokumentation.

Je nach Komplexität der Komponente benötigen Sie eventuell eine oder mehrere Registerkarten.

Dialoge für AEM-Komponenten:

In diesem Dialogfeld werden einzelne Felder definiert:

Design-Dialogfelder design-dialogs

Design-Dialogfelder ähneln den Dialogfeldern, die zum Bearbeiten und Konfigurieren von Inhalten genutzt werden. Sie stellen die Oberfläche für Vorlagenautoren bereit, um Design-Details für diese Komponente auf einer Seitenvorlage zu konfigurieren und bereitzustellen. Seitenvorlagen werden dann von den Inhaltsautoren verwendet, um Inhaltsseiten zu erstellen. Weitere Informationen zum Erstellen von Vorlagen finden Sie in der Vorlagendokumentation.

Design-Dialoge werden beim Bearbeiten einer Seitenvorlage verwendet, obwohl sie nicht für alle Komponenten benötigt werden. Zum Beispiel verfügen die Titel- und Bildkomponente beide über Design-Dialoge, während die Komponente für Freigabe in Social Media keine besitzt.

Coral- und Granite-Benutzeroberfläche coral-and-granite

Die Coral-Benutzeroberfläche und die Granite-Benutzeroberfläche definieren das Erscheinungsbild von AEM.

Die Granite-Benutzeroberfläche bietet einen großen Bereich der grundlegenden Widgets, die zum Erstellen Ihres Dialogfelds in der Authoring-Umgebung benötigt werden. Falls erforderlich, können Sie diese Auswahl erweitern und Ihr eigenes Widget erstellen.

Weitere Informationen finden Sie in den folgenden Ressourcen:

Anpassen von Dialogfeldern customizing-dialog-fields

Um ein Widget zur Verwendung in einem Komponentendialogfeld zu erstellen, müssen Sie eine Granite-Benutzeroberflächenfeldkomponente erstellen.

Wenn Sie das Dialogfeld für einen einfachen Container für ein Formularelement halten, können Sie den Primärinhalt Ihres Dialogfeldinhalts auch als Formularfelder sehen. Um ein neues Formularfeld zu erstellen, müssen Sie einen Ressourcentyp erstellen. Dies entspricht dem Erstellen einer Komponente. Um Ihnen bei dieser Aufgabe zu helfen, bietet die Granite-Benutzeroberfläche eine generische Feldkomponente, von der eine Vererbung möglich ist (mithilfe von sling:resourceSuperType):

/libs/granite/ui/components/coral/foundation/form/field

Genauer gesagt bietet die Granite-Benutzeroberfläche eine Reihe von Feldkomponenten, die für die Verwendung in Dialogfeldern, oder allgemeiner gesagt in Formularen, geeignet sind.

Sobald Sie Ihren Ressourcentyp erstellt haben, können Sie Ihr Feld instanziieren, indem Sie in Ihrem Dialogfeld einen neuen Knoten hinzufügen, wobei die Eigenschaft sling:resourceType auf den Ressourcentyp verweist, den Sie gerade eingeführt haben.

Zugriff auf Dialogfelder access-to-dialog-fields

Sie können auch Render-Bedingungen (rendercondition) verwenden, um festzulegen, wer Zugriff auf bestimmte Registerkarten/Felder in Ihrem Dialogfeld hat. Beispielsweise:

+ mybutton
  - sling:resourceType = granite/ui/components/coral/foundation/button
  + rendercondition
    - sling:resourceType = myapp/components/renderconditions/group
    - groups = ["administrators"]

Verwenden von Komponenten using-components

Nachdem Sie eine Komponente erstellt haben, müssen Sie sie aktivieren, um sie zu verwenden. Bei der Verwendung zeigt sich, wie sich die Struktur der Komponente auf die Struktur des resultierenden Inhalts im Repository bezieht.

Hinzufügen einer Komponente zur Vorlage adding-your-component-to-the-template

Nachdem eine Komponente definiert wurde, muss sie zur Verwendung bereitgestellt werden. Um eine Komponente für die Verwendung in einer Vorlage verfügbar zu machen, müssen Sie die Komponente in der Richtlinie des Layout-Containers der Vorlage aktivieren.

Weitere Informationen zum Erstellen von Vorlagen finden Sie in der Vorlagendokumentation.

Komponenten und die von ihnen erstellten Inhalte components-and-the-content-they-create

Wir erstellen und konfigurieren eine Instanz der Titelkomponente auf der Seite: /content/wknd/language-masters/en/adventures/extreme-ironing.html

Dann sehen wir die Struktur des Inhalts, der innerhalb des Repositorys erstellt wurde:

Insbesondere, wenn Sie sich den tatsächlichen Text einer Titelkomponente ansehen:

Die definierten Eigenschaften sind von den einzelnen Definitionen abhängig. Zwar können sie komplexer als oben dargestellt sein, folgen aber dennoch denselben grundlegenden Prinzipien.

Komponentenhierarchie und Vererbung component-hierarchy-and-inheritance

Komponenten in AEM unterliegen der Ressourcentyphierarchie. Diese wird verwendet, um Komponenten mit der sling:resourceSuperType-Eigenschaft zu erweitern. Dies ermöglicht es der Komponente, von einer anderen Komponente zu erben.

Weitere Informationen finden Sie im Abschnitt Wiederverwenden von Komponenten.

Bearbeitungsverhalten edit-behavior

In diesem Abschnitt wird beschrieben, wie Sie das Bearbeitungsverhalten einer Komponente konfigurieren. Dies umfasst Attribute wie für die Komponente verfügbare Aktionen, Merkmale des Kontext-Editors und die Listener, die sich auf Ereignisse in der Komponente beziehen.

Um das Bearbeitungsverhalten einer Komponente zu konfigurieren, fügen Sie einen cq:editConfig-Knoten des Typs cq:EditConfig unter dem Komponentenknoten (des Typs cq:Component) hinzu sowie spezifische Eigenschaften und untergeordnete Knoten. Die folgenden Funktionen und untergeordneten Knoten sind verfügbar:

In AEM sind viele Konfigurationen vorhanden. Sie können mit dem Abfrage-Tool in CRXDE Lite einfach nach bestimmten Eigenschaften oder untergeordneten Knoten suchen.

Komponenten-Platzhalter component-placeholders

Komponenten müssen immer HTML-Inhalte wiedergeben, die für den Autor sichtbar sind, auch wenn die Komponente keinen Inhalt hat. Andernfalls könnte sie visuell aus der Benutzeroberfläche des Editors verschwinden, sodass sie zwar technisch vorhanden, aber auf der Seite und im Editor unsichtbar ist. In einem solchen Fall sind die Autoren nicht in der Lage, die leere Komponente auszuwählen und mit ihr zu interagieren.

Aus diesem Grund sollten Komponenten einen Platzhalter darstellen, solange sie beim Rendern der Seite im Seiteneditor (wenn der WCM-Modus edit oder preview ist) keine sichtbare Ausgabe erzeugen.
Das typische HTML-Markup für einen Platzhalter sieht wie folgt aus:

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

Das typische HTL-Skript, das den obigen Platzhalter-HTML-Code rendert, lautet wie folgt:

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

Im vorherigen Beispiel ist isEmpty eine Variable, die nur dann wahr ist, wenn die Komponente keinen Inhalt hat und für den Autor unsichtbar ist.

Um Wiederholungen zu vermeiden, empfiehlt Adobe den Implementierern von Komponenten, eine HTL-Vorlage für diese Platzhalter zu verwenden, wie sie von den Kernkomponenten bereitgestellt wird.

Die Verwendung der Vorlage im vorherigen Link erfolgt dann mit der folgenden HTL-Zeile:

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

Im vorherigen Beispiel ist model.text die Variable, die nur dann wahr ist, wenn die Komponente einen Inhalt hat und sichtbar ist.

Eine beispielhafte Verwendung dieser Vorlage ist in den Kernkomponenten zu sehen, wie z. B. in der Titelkomponente.

Konfigurieren mit untergeordneten cq:EditConfig-Knoten configuring-with-cq-editconfig-child-nodes

Ablegen von Assets in einem Dialogfeld – cq:dropTargets cq-droptargets

Der Knoten cq:dropTargets (Knotentyp nt:unstructured) legt die Ablageziele fest, die eine Ablage von einem Asset aus dem Content Finder akzeptieren können. Er ist ein Knoten vom Typ cq:DropTargetConfig.

Der untergeordnete Knoten vom Typ cq:DropTargetConfig definiert ein Ablageziel in der Komponente.

Bearbeitung im Kontext – cq:inplaceEditing cq-inplaceediting

Ein Editor für die Bearbeitung im Kontext ermöglicht es dem Benutzer, Inhalte direkt im Inhaltsfluss zu bearbeiten, ohne dass ein Dialogfeld geöffnet werden muss. Zum Beispiel haben die Standardkomponenten für Text und Titel beide einen Editor für die Bearbeitung im Kontext.

Ein Editor für die Bearbeitung im Kontext ist nicht für jeden Komponententyp notwendig/sinnvoll.

Der Knoten cq:inplaceEditing (Knotentyp cq:InplaceEditingConfig) legt eine Kontextbearbeitungsfunktion für die Komponente fest. Er kann die folgenden Eigenschaften aufweisen:

Die folgende Konfiguration aktiviert die Bearbeitung der Komponente im Kontext und legt plaintext als Editor-Typ fest:

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

Handhabung von Feldereignissen – cq:listeners cq-listeners

Die Methode zur Handhabung von Ereignissen in Dialogfeldern wird jetzt mit Listenern in einer benutzerdefinierten Client-Bibliothek ausgeführt.

Um Logik in Ihr Feld zu injizieren, sollten Sie Folgendes beachten:

Um dies zu erreichen, müssen Sie die zugrunde liegende Widget-Bibliothek kennen, mit der Sie interagieren möchten. Informationen darüber, auf welches Ereignis Sie reagieren möchten, finden Sie in der Dokumentation zur Coral-Benutzeroberfläche.

Der Knoten cq:listeners (Knotentyp cq:EditListenersConfig) legt fest, was geschieht, bevor oder nachdem eine Aktion auf der Komponente stattfindet. In der folgenden Tabelle sind die möglichen Eigenschaften aufgeführt.

Der Ereignis-Handler kann mit einer benutzerdefinierten Implementierung implementiert werden. Zum Beispiel (hier ist project.customerAction eine statische Methode):

afteredit = "project.customerAction"

Das folgende Beispiel entspricht der Konfiguration REFRESH_INSERTED:

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

Mit der folgenden Konfiguration wird die Seite aktualisiert, nachdem die Komponente gelöscht, bearbeitet, eingefügt oder verschoben wurde:

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

Feldüberprüfung field-validation

Die Feldüberprüfung in der Granite-Benutzeroberfläche und den Granite-Benutzeroberflächen-Widgets erfolgt mithilfe der foundation-validation-API. Weitere Informationen finden Sie in der foundation-valdiation Granite-Dokumentation.

Erkennen der Verfügbarkeit des Dialogfelds dialog-ready

Wenn Sie über ein benutzerdefiniertes JavaScript verfügen, das nur ausgeführt werden muss, wenn das Dialogfeld verfügbar und bereit ist, sollten Sie auf das dialog-ready-Ereignis lauschen.

Dieses Ereignis wird ausgelöst, wenn das Dialogfeld geladen (oder erneut geladen) wird und einsatzbereit ist, d. h., wenn eine Änderung (Erstellen/Aktualisieren) im DOM des Dialogfelds erfolgt.

dialog-ready kann verwendet werden, um in JavaScript benutzerdefinierten Code einzubinden, der Anpassungen an den Feldern in einem Dialogfeld oder ähnliche Aufgaben durchführt.

Vorschauverhalten preview-behavior

Der WCM-Modus-Cookie wird beim Wechsel in den Vorschaumodus gesetzt, auch wenn die Seite nicht aktualisiert wird.

Komponenten mit einem Rendering, die für den WCM-Modus empfindlich sind, müssen so definiert werden, dass sie sich selbst aktualisieren und sich dann auf den Wert des Cookies verlassen.

Dokumentieren von Komponenten documenting-components

Als Entwickler möchten Sie einfachen Zugriff auf die Komponentendokumentation, damit Sie Folgendes der Komponente schnell verstehen können:

Aus diesem Grund ist es sehr einfach, einen vorhandenen Dokumentations-Markdown innerhalb der Komponente selbst vorzunehmen.

Sie müssen lediglich eine README.md-Datei in der Komponentenstruktur platzieren.

Dieser Markdown wird dann in der Komponentenkonsole angezeigt.

Der unterstützte Markdown ist derselbe wie der für Inhaltsfragmente.