Entwickeln von AEM-Komponenten developing-aem-components

AEM-Komponenten werden verwendet, um den Inhalt, den Sie auf Ihren Web-Seiten bereitstellen, zu speichern, zu formatieren und zu rendern.

Code-Beispiele code-samples

Diese Seite enthält die Referenzdokumentation (oder Links zur Referenzdokumentation) die für die Entwicklung neuer Komponenten für AEM erforderlich sind. Einige praktische Beispiele finden Sie unter Entwickeln von AEM-Komponenten - Codebeispiele.

Struktur structure

Die grundlegende Struktur einer Komponente wird auf der Seite AEM Komponenten - Grundlagen beschrieben. Dieses Dokument gilt sowohl für die Touch-optimierte als auch für die klassische Benutzeroberfläche. Auch wenn Sie die klassischen Einstellungen in Ihrer neuen Komponente nicht verwenden müssen, kann es hilfreich sein, sie beim Erben von vorhandenen Komponenten zu beachten.

Erweitern vorhandener Komponenten und Dialogfelder extending-existing-components-and-dialogs

Je nach der Komponente, die Sie implementieren möchten, kann es möglich sein, eine vorhandene Instanz zu erweitern oder anzupassen, anstatt die gesamte Struktur von Grund auf neu zu definieren und zu entwickeln.

Beim Erweitern oder Anpassen einer vorhandenen Komponente oder eines vorhandenen Dialogfelds können Sie entweder die gesamte Struktur oder nur die für das Dialogfeld erforderliche Struktur kopieren oder replizieren, bevor Sie Ihre Änderungen vornehmen.

Erweitern einer vorhandenen Komponente extending-an-existing-component

Das Erweitern einer vorhandenen Komponente kann mit der Ressourcentyphierarchie und den zugehörigen Vererbungsmechanismen erreicht werden.

Anpassen eines vorhandenen Komponentendialogfelds customizing-a-existing-component-dialog

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 (mit sling:resourceSuperType). Dies ist jetzt die empfohlene Methode zum Erweitern eines Komponentendialogfelds

Weitere Einzelheiten finden Sie unter Sling Resource Merger.

Definieren von Markup defining-the-markup

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

Verwenden der HTML-Vorlagensprache using-the-html-template-language

Die HTML Vorlagensprache (HTL), die mit AEM 6.0 eingeführt wurde, löst JSP (JavaServer Pages) als bevorzugtes und empfohlenes serverseitiges Vorlagensystem für HTML ab. HTL hilft Web-Entwicklungspersonen, die zuverlässige Unternehmens-Websites erstellen müssen, die Sicherheit und die Entwicklungseffizienz zu erhöhen.

Entwickeln der Inhaltslogik developing-the-content-logic

Diese optionale Logik wählt und/oder berechnet den Inhalt, der gerendert werden soll. Sie wird mit dem entsprechenden Anwendungs-API-Muster aus HTL-Ausdrücken aufgerufen.

Der Mechanismus zum Trennen der Logik von der Erscheinung hilft zu verdeutlichen, was für eine gegebene Sicht aufgerufen wird. Er ermöglicht auch eine unterschiedliche Logik für verschiedene Ansichten derselben Ressource.

Verwendung von Java using-java

Mit der Java-Anwendungs-API von HTL kann eine HTL-Datei auf Hilfsmethoden in einer benutzerdefinierten Java-Klasse zugreifen.Dies ermöglicht es Ihnen, Java-Code zu verwenden, um die Logik zum Auswählen und Konfigurieren des Komponenteninhalts zu implementieren.

Verwenden von JavaScript using-javascript

Die HTL JavaScript Use-API ermöglicht es einer HTL-Datei, auf den in JavaScript geschriebenen Hilfscode zuzugreifen. Dies ermöglicht es Ihnen, JavaScript-Code zu verwenden, um die Logik zum Auswählen und Konfigurieren des Komponenteninhalts zu implementieren.

Verwendung Client-seitiger HTML-Bibliotheken using-client-side-html-libraries

Moderne Websites beruhen in hohem Maße auf der Client-seitigen Verarbeitung durch einen komplexen JavaScript- und CSS-Code. Die Organisation und Optimierung der Bereitstellung dieses Codes kann äußerst kompliziert sein.

Um Abhilfe zu schaffen, stellt AEM Client-seitige Bibliotheksordner zur Verfügung, mit denen Sie Ihren Client-seitigen Code im Repository speichern, in Kategorien gruppieren und definieren können, wann und wie jede Code-Kategorie dem Client bereitgestellt werden soll. Das Client-seitige Bibliotheksystem übernimmt dann das Herstellen der richtigen Links auf der endgültigen Webseite, um den korrekten Code zu laden.

Lesen Sie Verwendung Client-seitiger HTML-Bibliotheken für weitere Informationen.

Konfigurieren des Bearbeitungsverhaltens configuring-the-edit-behavior

Sie können das Bearbeitungsverhalten einer Komponente konfigurieren, einschließlich Attributen wie Aktionen, die für die Komponente verfügbar sind, Eigenschaften des Editors für die Bearbeitung im Kontext, die sich auf Ereignisse für die Komponente beziehen. Die Konfiguration gilt dabei sowohl für die Touch-optimierte als auch für die klassische Benutzeroberfläche, wenn auch mit gewissen Unterschieden.

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.

Konfigurieren des Vorschauverhaltens configuring-the-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.

Erstellen und Konfigurieren eines Dialogfelds creating-and-configuring-a-dialog

Dialogfelder werden verwendet, um dem Autor die Interaktion mit der Komponente zu ermöglichen. Mit einem Dialogfeld können Autorinnen und Autoren und/oder Admins Inhalte bearbeiten, die Komponente konfigurieren oder Design-Parameter definieren (mit einem Design-Dialogfeld)

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

Die Coral-Benutzeroberfläche und die Granite-Benutzeroberfläche definieren das Look-and-Feel von AEM.

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

Ausführliche Informationen finden Sie hier:

Erstellen eines neuen Dialogfelds creating-a-new-dialog

Dialogfelder für die Touch-optimierte Benutzeroberfläche:

Eine Beispielknotenstruktur könnte wie folgt aussehen:

newComponent (cq:Component)
  cq:dialog (nt:unstructured)
    content
      layout
      items
        column
          items
            file
            description

Das Anpassen eines Dialogfelds ähnelt der Entwicklung einer Komponente, da das Dialogfeld selbst eine Komponente ist (d. h. Markup, das von einem Komponentenskript zusammen mit dem von einer Client-Bibliothek bereitgestellten Verhalten/Stil gerendert wird).

Beispiele finden Sie hier:

Anpassen von Dialogfeldern customizing-dialog-fields

Erstellen eines neuen Feldes creating-a-new-field

Widgets für die Touch-optimierte Benutzeroberfläche sind als Komponenten der Granite-Benutzeroberfläche implementiert.

Um für die Touch-optimierte Benutzeroberfläche ein Widget zur Verwendung in einem Komponentendialogfeld zu erstellen, müssen Sie eine Feldkomponente für die Granite-Benutzeroberfläche erstellen.

Wenn Sie das Dialogfeld als einen einfachen Container für ein Formularelement betrachten, können Sie den Primärinhalt Ihres Dialogfeldinhalts auch als Formularfelder ansehen. Zum Erstellen eines Formularfelds 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 allgemein 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.

Erstellen einer Client-Bibliothek für Stil und Verhalten creating-a-client-library-for-style-and-behavior

Wenn Sie Stil und Verhalten für Ihre Komponente definieren möchten, können Sie eine dedizierte Client-Bibliothek erstellen, die Ihre benutzerdefinierte CSS/LESS- und JS-Datei definiert.

Damit Ihre Client-Bibliothek nur für das Komponentendialogfeld geladen wird (d. h., sie wird nicht für eine andere Komponente geladen), müssen Sie die Eigenschaft extraClientlibs Ihres Dialogfelds auf den Kategorienamen der erstellten Client-Bibliothek festlegen. Dies empfiehlt sich, wenn die Client-Bibliothek recht groß ist und/oder das Feld für dieses Dialogfeld spezifisch ist und nicht in anderen Dialogfeldern benötigt wird.

Um die Client-Bibliothek für alle Dialogfelder zu laden, legen Sie die Kategorieeigenschaft Ihrer Client-Bibliothek auf cq.authoring.dialog fest. Dies ist der Kategoriename der Client-Bibliothek, die beim Rendern aller Dialogfelder standardmäßig enthalten ist. Dies empfiehlt sich, wenn die Client-Bibliothek klein ist und/oder Ihr Feld generisch ist und in anderen Dialogfeldern wiederverwendet werden kann.

Ein Beispiel finden Sie unter:

Erweitern (Vererben) von einem Feld extending-inheriting-from-a-field

Je nach Ihren Anforderungen haben Sie folgende Möglichkeiten:

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"]

Behandlung von Feldereignissen handling-field-events

Die Methode zur Behandlung von Ereignissen in Dialogfeldern wird jetzt mit Listenern in einer benutzerdefinierten Client-Bibliothek ausgeführt. Dies ist eine Änderung gegenüber der älteren Methode, Listener in der Inhaltsstruktur zu haben.

Listener in einer benutzerdefinierten Client-Bibliothek listeners-in-a-custom-client-library

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. Dies ähnelt dem Prozess, den Sie in der Vergangenheit mit ExtJS durchführen mussten: die Dokumentationsseite eines bestimmten Widgets suchen und dann die Details seiner Ereignis-API überprüfen.

Ein Beispiel finden Sie unter:

Listener in der Inhaltsstruktur listeners-in-the-content-structure

In der klassischen Benutzeroberfläche mit ExtJS war es üblich, Listener für ein bestimmtes Widget in der Inhaltsstruktur zu haben. Dasselbe muss in der Touch-optimierten Benutzeroberfläche auf andere Art erreicht werden, da der JS-Listener-Code (und überhaupt jeglicher Code) nicht mehr im Inhalt definiert ist.

Die Inhaltsstruktur beschreibt die semantische Struktur. Sie sollte (muss) nicht die Art des zugrunde liegenden Widget implizieren. Wenn Sie keinen JS-Code in der Inhaltsstruktur haben, können Sie die Implementierungsdetails ändern, ohne die Inhaltsstruktur ändern zu müssen. Mit anderen Worten: Sie können die Widget-Bibliothek ändern, ohne die Inhaltsstruktur anzutasten.

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

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.

Feldüberprüfung field-validation

Pflichtfeld mandatory-field

Legen Sie die folgende Eigenschaft im Inhaltsknoten Ihres Felds fest, um ein bestimmtes Feld als Pflichtfeld zu markieren:

Ein Beispiel finden Sie unter:

/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title

Feldvalidierung (Granite-Benutzeroberfläche) field-validation-granite-ui

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

Beispiele finden Sie hier:

Erstellen und Konfigurieren eines Design-Dialogfelds creating-and-configuring-a-design-dialog

Das Design-Dialogfeld wird bereitgestellt, wenn eine Komponente Entwurfsdetails enthält, die im Entwurfsmodus bearbeitet werden können.

Die Definition ist der eines Dialogfelds sehr ähnlich, das für die Bearbeitung von Inhalten verwendet wird, mit dem Unterschied, dass es als Knoten definiert ist:

Erstellen und Konfigurieren eines Editors für Bearbeitung im Kontext creating-and-configuring-an-inplace-editor

Ein Editor für die Bearbeitung im Kontext ermöglicht es dem Benutzer, Inhalte direkt im Absatzfluss zu bearbeiten, ohne dass ein Dialogfeld geöffnet werden muss. Zum Beispiel haben die Standardkomponenten „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.

Weitere Informationen finden Sie unter Erweiterung der Seitenerstellung – Hinzufügen eines neuen Editors für die Bearbeitung im Kontext.

Anpassen der Komponentensymbolleiste customizing-the-component-toolbar

Die Komponentensymbolleiste bietet Benutzenden Zugriff auf eine Reihe von Aktionen für die Komponente, z. B. Bearbeiten, Konfigurieren, Kopieren und Löschen.

Weitere Informationen finden Sie unter Erweiterung der Seitenerstellung – Hinzufügen einer neuen Aktion zu einer Komponentensymbolleiste.

Konfigurieren einer Komponente für die Verweisleiste (Geliehen/Verliehen) configuring-a-component-for-the-references-rail-borrowed-lent

Wenn Ihre neue Komponente auf Inhalte von anderen Seiten verweist, können Sie überlegen, ob sich dies auf die Abschnitte Geliehener Inhalt und Verliehener Inhalt der Verweis-Leiste auswirken soll.

Die Standardinstallation von AEM überprüft nur die Referenzkomponente. Um Ihre Komponente hinzuzufügen, müssen Sie die Referenzkonfiguration für das OSGi-Bundle WCM Authoring Content konfigurieren.

Erstellen Sie einen Eintrag in der Definition und geben Sie Ihre Komponente zusammen mit der zu überprüfenden Eigenschaft an. Zum Beispiel:

/apps/<*your-Project*>/components/reference@parentPath

Aktivieren und Hinzufügen Ihrer Komponente zum Absatzsystem enabling-and-adding-your-component-to-the-paragraph-system

Nachdem die Komponente entwickelt wurde, muss sie für die Verwendung in einem geeigneten Absatzsystem aktiviert werden, damit sie auf den erforderlichen Seiten verwendet werden kann.

Dies kann folgendermaßen erfolgen:

Konfigurieren eines Absatzsystems, sodass beim Ziehen eines Assets eine Komponenteninstanz erstellt wird configuring-a-paragraph-system-so-that-dragging-an-asset-creates-a-component-instance

AEM bietet die Möglichkeit, ein Absatzsystem auf Ihrer Seite so zu konfigurieren, dass automatisch eine Instanz der neuen Komponente erstellt wird, wenn Benutzende ein (geeignetes) Asset auf eine Instanz dieser Seite ziehen (anstatt immer eine leere Komponente auf die Seite ziehen zu müssen).

Dieses Verhalten und die erforderliche Beziehung zwischen Asset und Komponente können konfiguriert werden:

Beispiele finden Sie unter:

CODE AUF GITHUB

Den Code dieser Seite finden Sie auf GitHub.

Verwenden von AEM Brackets-Erweiterungen using-the-aem-brackets-extension

Die AEM Brackets-Erweiterung bietet einen reibungslosen Workflow zum Bearbeiten von AEM-Komponenten und Client-Bibliotheken. Sie basiert auf dem Brackets-Code-Editor.

Die Erweiterung:

Migration von einer klassischen Komponente migrating-from-a-classic-component

Wenn Sie eine Komponente, die für die Verwendung mit der klassischen Benutzeroberfläche konzipiert wurde, zu einer Komponente migrieren, die mit der Touch-optimierten Benutzeroberfläche (einzeln oder gemeinsam) verwendet werden kann, sollten die folgenden Probleme berücksichtigt werden:

Migrieren von cq:listener-Code migrating-cq-listener-code

Wenn Sie ein Projekt migrieren, das für die klassische Benutzeroberfläche konzipiert wurde, verwendet der cq:listener-Code (und komponentenbezogene Client-Bibliotheken) möglicherweise Funktionen, die für die klassische Benutzeroberfläche spezifisch sind (z. B. CQ.wcm.*). Für die Migration müssen Sie diesen Code mithilfe der entsprechenden Objekte/Funktionen in der Touch-optimierten Benutzeroberfläche aktualisieren.

Wenn Ihr Projekt vollständig in die Touch-optimierte Benutzeroberfläche migriert wird, müssen Sie diesen Code ersetzen, um die Objekte und Funktionen zu verwenden, die für die Touch-optimierte Benutzeroberfläche relevant sind.

Wenn Ihr Projekt jedoch während des Migrationszeitraums sowohl die klassische als auch die Touch-optimierte Benutzeroberfläche berücksichtigen muss (das übliche Szenario), müssen Sie einen Umschalter implementieren, um den separaten Code zu unterscheiden, der auf die entsprechenden Objekte verweist.

Dieser Umschaltmechanismus kann wie folgt implementiert werden:

if (Granite.author) {
    // touch UI
} else {
    // classic UI
}

Dokumentation der Komponente documenting-your-component

Wenn Sie mit der Entwicklung befasst sind, möchten Sie einen einfachen Zugriff auf die Komponentendokumentation haben, damit Sie Folgendes schnell verstehen können:

Dafür ist es sehr einfach, einen vorhandenen Dokumentations-Markdown innerhalb der Komponente selbst vorzunehmen.

Platzieren Sie eine README.md-Datei in die Komponentenstruktur. Dieser Markdown wird dann in der Komponentenkonsole angezeigt.

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