AEM-Komponenten – Grundlagen

Wenn Sie neue Komponenten entwickeln, müssen Sie die Grundlagen ihrer Struktur und Konfiguration kennen.

Dazu müssen Sie den theoretischen Hintergrund kennenlernen und sich mit den vielfältigen Komponenten-Implementierungen in einer standardmäßigen AEM-Instanz vertraut machen. Der zuletzt genannte Ansatz wird ein Stück weit durch die Tatsache erschwert, dass AEM zwar standardmäßig eine neue, moderne Touch-optimierte Benutzeroberfläche einsetzt, die klassische Benutzeroberfläche aber nach wie vor unterstützt.

Überblick

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

Planung

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

• Was genau soll die neue Komponente tun?
  • Eine eindeutige Spezifikation hilft in allen Phasen der Entwicklung, des Testings und der Übergabe. Details können sich im Laufe der Zeit ändern, woraufhin die Spezifikation jedoch aktualisiert werden kann (Änderungen sollten jedoch ebenso dokumentiert werden).
• Müssen Sie die Komponente komplett neu entwickeln oder können Sie die Grundlagen von einer vorhandenen Komponente übernehmen?
  • Sie müssen das Rad nicht neu erfinden.
  • Es gibt verschiedene Mechanismen, die von AEM bereitgestellt werden, um Ihnen zu ermöglichen, Details von einer anderen Komponentendefinition zu erben und zu erweitern, einschließlich Überschreiben, Überlagerung und dem Sling Resource Merger.
• Benötigt die Komponente eine Logik zur Auswahl/Bearbeitung des Inhalts?
  • Die Logik sollte getrennt von der Ebene der Benutzeroberfläche aufbewahrt werden. HTL dient dazu, dies sicherzustellen.
• Benötigt Ihre Komponente eine CSS-Formatierung?
  • Eine CSS-Formatierung sollte getrennt von den Komponentendefinitionen aufbewahrt werden. Legen Sie Konventionen für die Benennung der HTML-Elemente fest, damit Sie sie über externe CSS-Dateien modifizieren können.
• Welche Sicherheitsaspekte sollte ich berücksichtigen?
  • Weitere Informationen finden Sie unter Sicherheits-Checkliste – Best Practices für die Entwicklung.

Vergleich zwischen Touch-optimierter und klassischer Benutzeroberfläche

Bevor es um die Entwicklung von Komponenten geht, müssen Sie wissen, welche Benutzeroberfläche Ihre Autoren verwenden:

• Touch-optimierte Benutzeroberfläche
  Die Standardbenutzeroberfläche basiert auf dem einheitlichen Benutzererlebnis für die Adobe Marketing Cloud und verwendet dabei die zugrunde liegenden Technologien der Coral- Benutzeroberfläche und der Granite-Benutzeroberfläche.
• Klassische
  Benutzeroberfläche auf Basis der ExtJS-Technologie, die seit AEM 6.4 veraltet ist.

Weitere Informationen finden Sie unter Benutzeroberflächen-Empfehlungen für Kunden.

Komponenten können je nach Implementierung die Touch-optimierte Benutzeroberfläche, die klassische oder beide Versionen unterstützen. Wenn Sie sich eine Standardinstanz ansehen, sehen Sie auch vordefinierte Komponenten, die ursprünglich für die klassische Benutzeroberfläche, die Touch-optimierte Benutzeroberfläche oder beides entwickelt wurden.

Daher werden auf dieser Seite die Grundlagen und die Erkennungsmerkmale beider Versionen abgedeckt.

Inhaltslogik und Rendering-Markup

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. Diese (optionale) Logik wird von HTL über einen speziellen Befehl aufgerufen. Dieser Mechanismus kennzeichnet den Code, der für eine bestimmte Ansicht aufgerufen wird, und lässt bei Bedarf eine spezifische Logik für unterschiedliche Ansichten derselben Komponente zu.

Vergleich zwischen HTL und JSP

HTL ist eine HTML-Vorlagensprache, die mit AEM 6.0 eingeführt wurde.

Die Frage, ob Sie bei der Entwicklung eigener Komponenten HTL oder JSP (Java Server Pages) nutzen sollten, ist leicht zu beantworten – immerhin ist HTL nun die empfohlene Skriptsprache für AEM.

Sie können sowohl HTL als auch JSP für die Entwicklung von Komponenten für die klassische wie die Touch-optimierte Benutzeroberfläche verwenden. Zwar wird häufig angenommen, dass HTL nur für die Touch-optimierte und JSP für die klassische Benutzeroberfläche ist, doch diese Vermutung ist falsch und wohl auf die Tatsache zurückzuführen, dass die Touch-optimierte Benutzeroberfläche und HTL ungefähr zur selben Zeit in AEM integriert wurden. Da HTL nun die empfohlene Sprache ist, wird sie für neue Komponenten verwendet, die meistens für die Touch-optimierte Benutzeroberfläche ausgelegt sind.

Entwickeln eigener Komponenten

Informationen zum Erstellen eigener Komponenten für die entsprechende Benutzeroberfläche finden Sie (nach dem Lesen dieser Seite) unter:

• AEM-Komponenten für die Touch-optimierte Benutzeroberfläche
• AEM-Komponenten für die klassische Benutzeroberfläche

Eine schnelle Möglichkeit für den Einstieg ist das Kopieren einer vorhandenen Komponente und das anschließende Vornehmen der gewünschten Änderungen. Informationen dazu, wie Sie Ihre eigenen Komponenten erstellen und sie zum Absatzsystem hinzufügen, finden Sie unter:

• Entwickeln von Komponenten (mit Schwerpunkt auf der Touch-optimierten Benutzeroberfläche)

Verschieben von Komponenten in die Veröffentlichungsinstanz

Die Komponenten, die Inhalte rendern, müssen auf derselben AEM-Instanz bereitgestellt werden wie die Inhalte. Daher müssen alle Komponenten, die zum Verfassen und Rendern von Seiten auf der Autoreninstanz genutzt werden, auf der Veröffentlichungsinstanz bereitgestellt werden. Wenn sie bereitgestellt sind, stehen diese Komponenten zum Rendern aktivierter Seiten zur Verfügung.

Mit den folgenden Tools können Sie Ihre Komponenten in die Veröffentlichungsinstanz verschieben:

• Verwenden Sie Package Manager, um Ihre Komponenten einem Paket hinzuzufügen und in eine andere AEM Instanz zu verschieben.
• Mit dem Replikationstool „Tree aktivieren“ können Sie die Komponenten replizieren.

Komponenten, die Sie von Anfang an kennen sollten

• Seite:

  • AEM hat die Komponente page ( cq:Page).
  • Dabei handelt es sich um eine bestimmte Art von Ressource, die für das Content-Management wichtig ist.
    • Eine Seite entspricht einer Webseite, die Inhalte für Ihre Website enthält.

• Absatzsysteme:

  • Das Absatzsystem ist eine wichtige Komponente einer Website, da es eine Liste an Absätzen verwaltet. Mit dem Absatzsystem werden die einzelnen Komponenten gespeichert und strukturiert, die die eigentlichen Inhalte enthalten.
  • Sie können Absätze im Absatzsystem erstellen, verschieben, kopieren und löschen.
  • Sie können auch Komponenten auswählen, die zur Verwendung in einem bestimmten Absatzsystem verfügbar sein sollen.
  • Es gibt verschiedene Absatzsysteme in einer Standardinstanz (z. B. parsys, [responsivegrid](/docs/experience-manager-65/sites-authoring/responsive-layout.md)).

Struktur

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

• Ressourcentyp
• Komponentendefinition
• Eigenschaften und untergeordnete Knoten einer Komponente
• Dialogfelder
• Design-Dialogfelder
• Verfügbarkeit von Komponenten
• Komponenten und die von ihnen erstellten Inhalte

Ressourcentyp

Ein zentrales Element der Struktur ist der Ressourcentyp.

• Die Inhaltsstruktur deklariert Absichten.
• Der Ressourcentyp implementiert sie.

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

Komponentendefinition

Komponenten – Grundlagen

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

• AEM-Komponenten basieren auf Sling.

• AEM-Komponenten befinden sich (in der Regel) unter:

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

• Projekt- bzw. Website-spezifische Komponenten befinden sich (in der Regel) unter:

  • /apps/<myApp>/components

• AEM-Standardkomponenten sind als cq:Component definiert und haben die folgenden zentralen Elemente:

  • jcr-Eigenschaften:

    eine Liste der jcr-Eigenschaften; diese sind variabel und einige können optional sein, obwohl die grundlegende Struktur eines Komponentenknotens, seiner Eigenschaften und Unterknoten durch die cq:Component-Definition definiert wird.

  • Ressourcen:

    Diese definieren statische Elemente, die von der Komponente verwendet werden.

  • Skripte:

  werden verwendet, um das Verhalten der resultierenden Instanz der Komponente zu implementieren.

• Stammknoten:

  • <mycomponent> (cq:Component) – Hierarchieknoten der Komponente.

• Wichtige Eigenschaften:

  • jcr:title – Komponententitel; wird beispielsweise als Kennzeichnung genutzt, wenn die Komponente im Komponenten-Browser oder Sidekick aufgeführt wird

  • jcr:description – Beschreibung der Komponente; kann als Mouseover-Hinweis im Komponenten-Browser oder Sidekick genutzt werden

  • Klassische Benutzeroberfläche:

    • icon.png - Symbol für diese Komponente.
    • thumbnail.png – Bild, das angezeigt wird, wenn diese Komponente im Absatzsystem aufgeführt wird

  • Touch-optimierte Benutzeroberfläche

    • Detaillierte Informationen finden Sie unter Komponentensymbol in der Touch-optimierten Benutzeroberfläche.

• Wichtige untergeordnete Knoten:

  • cq:editConfig (cq:EditConfig) - Definiert die Bearbeitungseigenschaften der Komponente und ermöglicht das Anzeigen der Komponente im Komponenten-Browser oder Sidekick.

    Hinweis: Wenn die Komponente über ein Dialogfeld verfügt, wird sie automatisch im Komponenten-Browser oder Sidekick aufgeführt, selbst wenn die cq:editConfig nicht vorhanden ist.

  • cq:childEditConfig (cq:EditConfig) – Steuert Aspekte der Autoren-Benutzeroberfläche für untergeordnete Komponenten, die keine eigene cq:editConfig definieren.

  • Touch-optimierte Benutzeroberfläche:

    • cq:dialog ( nt:unstructured) - Dialogfeld für diese Komponente. Definiert die Oberfläche, über die Benutzer die Komponente konfigurieren und/oder Inhalte bearbeiten können.
    • cq:design_dialog ( nt:unstructured) - Designbearbeitung für diese Komponente

  • Klassische Benutzeroberfläche:

    • dialog ( cq:Dialog) - Dialogfeld für diese Komponente. Definiert die Oberfläche, über die Benutzer die Komponente konfigurieren und/oder Inhalte bearbeiten können.
    • design_dialog ( cq:Dialog) - Designbearbeitung für diese Komponente.

Komponentensymbol in der Touch-optimierten Benutzeroberfläche

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.

1. cq:icon – Zeichenfolgeneigenschaft, die auf ein Standardsymbol in der Bibliothek der Coral-Benutzeroberfläche verweist, das im Komponenten-Browser angezeigt werden soll.
   • Verwenden Sie den Wert des HTML-Attributs des Coral-Symbols.
2. abbreviation – Zeichenfolgeneigenschaft, die die Abkürzung des Komponentennamens im Komponenten-Browser anpasst.
   • Die Abkürzung sollte auf zwei Zeichen beschränkt sein.
   • Bei einer leeren Zeichenfolge wird die Abkürzung aus den ersten beiden Buchstaben der Eigenschaft jcr:title gebildet.
     • Beispiel: „Gr“ für „Grafik“.
     • Zum Erstellen der Abkürzung wird der lokalisierte Titel verwendet.
   • Die Abkürzung wird nur übersetzt, wenn die Komponente die Eigenschaft abbreviation_commentI18n aufweist, die dann als Anweisung für eine Übersetzung genutzt wird.
3. cq:icon.png oder cq:icon.svg - Symbol für diese Komponente, das im Komponenten-Browser angezeigt wird
   • Symbole von Standardkomponenten haben eine Größe von 20 x 20 Pixeln.
     • Größere Symbole werden verkleinert (Client-seitig).
   • Die empfohlene Farbe ist rgb(112, 112, 112) > #707070.
   • Der Hintergrund von Symbolen von Standardkomponenten ist transparent.
   • Es werden nur .png- und .svg-Dateien unterstützt.
   • Beim Importieren aus dem Dateisystem über das Eclipse-Plug-in müssen die Dateinamen nach folgendem Schema geändert werden: z. B. _cq_icon.png oder _cq_icon.svg.
   • .png hat Vorrang vor , .svg wenn beide vorhanden sind

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

• Das System sucht nach denselben Eigenschaften bei den übergeordneten Komponenten, die der Eigenschaft sling:resourceSuperType folgen.
• Wenn auf der Ebene der übergeordneten Komponente nichts oder eine leere Abkürzung gefunden wird, erstellt das System die Abkürzung aus den ersten beiden Zeichen der Eigenschaft jcr:title der aktuellen Komponente.

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

<?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

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 Text-Komponente (beide Versionen) finden sich die folgenden Elemente:

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

  

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

  

Zu den wichtigen Eigenschaften gehören:

• jcr:title – Titel der Komponente; dient zur Identifizierung der Komponente, z. B. in der Komponentenliste im Komponenten-Browser oder Sidekick
• jcr:description – Beschreibung der Komponente; kann als Mouseover-Hinweis in der Komponentenliste im Sidekick genutzt werden
• sling:resourceSuperType – gibt den Pfad der Vererbung bei der Erweiterung einer Komponente an (durch Überschreiben einer Definition)

Zu den wichtigen untergeordneten Knoten gehören:

• cq:editConfig ( cq:EditConfig) - Diese Funktion steuert visuelle Aspekte. Sie kann beispielsweise das Erscheinungsbild einer Leiste oder eines Widgets definieren oder benutzerdefinierte Steuerelemente hinzufügen
• cq:childEditConfig ( cq:EditConfig) - Dies steuert die visuellen Aspekte für untergeordnete Komponenten, die keine eigenen Definitionen haben
• Touch-optimierte Benutzeroberfläche:
  • cq:dialog ( nt:unstructured) - definiert das Dialogfeld zum Bearbeiten des Inhalts dieser Komponente
  • cq:design_dialog ( nt:unstructured) - gibt die Designbearbeitungsoptionen für diese Komponente an
• Klassische Benutzeroberfläche:
  • dialog ( cq:Dialog) - definiert das Dialogfeld zum Bearbeiten des Inhalts dieser Komponente (spezifisch für die klassische Benutzeroberfläche)
  • design_dialog ( cq:Dialog) - gibt die Designbearbeitungsoptionen für diese Komponente an
  • icon.png – Grafikdatei, die als Symbol für die Komponente im Sidekick genutzt werden soll
  • thumbnail.png – Grafikdatei, die als Miniaturansicht der Komponente beim Ziehen aus dem Sidekick genutzt werden soll

Dialogfelder

Dialogfelder sind ein wichtiges Element einer Komponente: Sie stellen den Autoren eine Oberfläche für die Konfiguration und für Eingaben für diese Komponente bereit.

Je nach Komplexität der Komponente benötigt das Dialogfeld eine Registerkarte oder mehrere, um das Dialogfeld übersichtlich zu gestalten und die Eingabefelder zu ordnen.

Dialogdefinitionen sind spezifisch für jede Benutzeroberfläche.

• Touch-optimierte Benutzeroberfläche

  • cq:dialog ( nt:unstructured) nodes:
    • definieren das Dialogfeld für die Bearbeitung von Inhalten dieser Komponente
    • speziell für die Touch-optimierte Benutzeroberfläche
    • werden mit Komponenten der Granite-Benutzeroberfläche definiert
    • haben eine Eigenschaft sling:resourceType als standardmäßige Sling-Inhaltsstruktur
    • können die Eigenschaft helpPath aufweisen, um die kontextabhängige Hilferessource festzulegen (absoluter oder relativer Pfad), auf die bei Auswahl des Hilfesymbols -Symbol) ausgewählt ist.
      • Bei standardmäßigen Komponenten verweist diese Eigenschaft häufig auf eine Seite in der Dokumentation.
      • Wenn kein helpPath festgelegt ist, wird die Standard-URL (Übersichtsseite der Dokumentation) angezeigt.

  

  In diesem Dialogfeld werden einzelne Felder definiert:

  

• Klassische Benutzeroberfläche

  • dialog ( cq:Dialog) nodes
    • definieren das Dialogfeld für die Bearbeitung von Inhalten dieser Komponente
    • speziell für die klassische Benutzeroberfläche
    • werden mit ExtJS-Widgets definiert
    • weisen die Eigenschaft xtype auf, die auf ExtJS verweist
    • können die Eigenschaft helpPath aufweisen, um die kontextabhängige Hilferessource festzulegen (absoluter oder relativer Pfad), auf die bei Klicken auf die Schaltfläche Hilfe zugegriffen wird.
      • Bei standardmäßigen Komponenten verweist diese Eigenschaft häufig auf eine Seite in der Dokumentation.
      • Wenn kein helpPath festgelegt ist, wird die Standard-URL (Übersichtsseite der Dokumentation) angezeigt.

  

  In diesem Dialogfeld werden einzelne Felder definiert:

  

  In einem klassischen Dialogfeld:

  • können Sie Dialogfeld wie cq:Dialog erstellen, die eine einzige Registerkarte aufweisen, wie in der Text-Komponente. Wenn Sie mehrere Registerkarten benötigen, wie in der Textbild-Komponente, können Sie das Dialogfeld als cq:TabPanel definieren.
  • Ein cq:WidgetCollection ( items) wird verwendet, um eine Basis für Eingabefelder ( cq:Widget) oder weitere Registerkarten ( cq:Widget) bereitzustellen. Diese Hierarchie kann erweitert werden.

Design-Dialogfelder

Designdialogfelder ähneln den Dialogfeldern, die zum Bearbeiten und Konfigurieren von Inhalten genutzt werden. Sie stellen die Oberfläche für Autoren zum Konfigurieren bereit und liefern Designinformationen für diese Komponente.

Designdialogfelder sind im Designmodus verfügbar, wobei sie nicht für alle Komponenten benötigt werden. Beispielsweise verfügen sowohl Titel als auch Bild über Designdialogfelder, Text dagegen nicht.

Das Designdialogfeld für das Absatzsystem (z. B. parsys) ist ein Sonderfall: Benutzer können damit andere Komponenten festlegen, die auf der Seite zur Auswahl (über den Komponenten-Browser oder Sidekick) verfügbar sein sollen.

Hinzufügen einer Komponente zum Absatzsystem

Nachdem eine Komponente definiert wurde, muss sie zur Verwendung bereitgestellt werden. Um eine Komponente zur Verwendung in einem Absatzsystem bereitzustellen, haben Sie zwei Möglichkeiten:

1. Öffnen Sie den Designmodus für eine Seite und aktivieren Sie die benötigte Komponente.

2. Fügen Sie die benötigte(n) Komponente(n) zur Eigenschaft components der Vorlagendefinition unter folgendem Pfad hinzu:

   /etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par

   Ein Beispiel finden Sie unter:

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

   

Komponenten und die von ihnen erstellten Inhalte

Wir erstellen und konfigurieren eine Instanz der Titelkomponente auf der Seite: <content-path>/Prototype.html

• Touch-optimierte Benutzeroberfläche

  

• Klassische Benutzeroberfläche

  

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

Sehen Sie sich besonders den tatsächlichen Text für eine Titel-Komponente an:

• Die Definition weist (bei beiden Benutzeroberflächen) die Eigenschaft name= ./jcr:title

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

• Innerhalb des Inhalts wird dadurch die Eigenschaft jcr:title erstellt, die den Inhalt des Autors enthält.

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

Komponenten in AEM unterliegen drei verschiedenen Hierarchien:

• Ressourcentyphierarchie

  Diese wird verwendet, um Komponenten mit der sling:resourceSuperType-Eigenschaft zu erweitern. Dies aktiviert die Vererbung für die Komponente. Beispielsweise erbt eine Textkomponente verschiedene Attribute von der Standardkomponente.

  • Skripte (aufgelöst durch Sling)
  • Dialogfelder
  • Beschreibungen (darunter Miniaturansichten, Symbole usw.)

• Behälterhierarchie

  Dies wird zum Füllen der Konfigurationseinstellungen in die untergeordnete Komponente verwendet und am häufigsten in einem Parsys-Szenario verwendet.

  So können Sie beispielsweise Konfigurationseinstellungen für die Schaltflächen auf der Bearbeitungsleiste, das Layout von Steuerungen (Bearbeitungsleiste, Rollover) oder von Dialogfeldern (eingebunden, unverankert) auf der übergeordneten Komponente definieren und an die untergeordneten Komponenten übergeben.

  Konfigurationseinstellungen (im Zusammenhang mit der Bearbeitungsfunktion) in cq:editConfig und cq:childEditConfig werden übertragen.

• Einschlusshierarchie

  Dies wird zur Laufzeit durch die Reihenfolge der Includes festgelegt.

  Diese Hierarchie wird vom Designer verwendet, der als Basis für die verschiedenen Designaspekte des Rendering fungiert; einschließlich Layoutangaben, CSS-Informationen, verfügbaren Komponenten in einem parsys usw.

Bearbeitungsverhalten

In diesem Abschnitt wird beschrieben, wie Sie das Bearbeitungsverhalten einer Komponente konfigurieren. Hierzu zählen Attribute wie Aktionen, die für die Komponente verfügbar sind, Eigenschaften des Kontext-Editors und des Listeners in Zusammenhang mit Ereignissen bei der Komponente.

Die Konfiguration gilt dabei für die Touch-optimierte wie 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. Die folgenden Funktionen und untergeordneten Knoten sind verfügbar:

• cq:editConfig Knoteneigenschaften:

  • cq:actions ( String array): definiert die Aktionen, die für die Komponente ausgeführt werden können.

  • cq:layout ( String): : definiert, wie die Komponente in der klassischen Benutzeroberfläche bearbeitet wird.

  • cq:dialogMode ( String): definiert, wie das Komponentendialogfeld in der klassischen Benutzeroberfläche geöffnet wird

    • In der Touch-optimierten Benutzeroberfläche sind die Dialogfelder im Desktopmodus immer unverankert und werden im mobilen Modus immer im Vollbild geöffnet.

  • cq:emptyText ( String): definiert Text, der angezeigt wird, wenn kein visueller Inhalt vorhanden ist.

  • cq:inherit ( Boolean): definiert, ob fehlende Werte von der Komponente übernommen werden, von der sie übernommen werden.

  • dialogLayout (String): legt fest, wie das Dialogfeld geöffnet werden soll

• cq:editConfigUntergeordnete -Knoten:

  • cq:dropTargets (Knotentyp nt:unstructured): definiert eine Liste von Ablagezielen, die eine Ablage aus einem Asset des Content Finders akzeptieren können

    • Mehrere Ablageziele sind nur in der klassischen Benutzeroberfläche verfügbar.
    • In der Touch-optimierten Benutzeroberfläche ist nur ein einziges Ablageziel zulässig.

  • cq:actionConfigs (Knotentyp nt:unstructured): definiert eine Liste neuer Aktionen, die an die Liste cq:actions angehängt werden.

  • cq:formParameters (Knotentyp nt:unstructured): definiert zusätzliche Parameter, die dem Dialogfeldformular hinzugefügt werden.

  • cq:inplaceEditing (Knotentyp cq:InplaceEditingConfig): definiert eine Konfiguration für die Bearbeitung im Kontext für die Komponente.

  • cq:listeners (Knotentyp cq:EditListenersConfig): Legt fest, was geschieht, bevor oder nachdem eine Aktion auf der Komponente stattfindet.

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://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>

Es gibt zahlreiche vorhandene Konfigurationen im Repository. Sie können einfach nach bestimmten Eigenschaften oder untergeordneten Knoten suchen:

• Um nach einer Eigenschaft des Knotens cq:editConfig zu suchen, z. B. cq:actions können Sie das Abfragetool in CRXDE Lite verwenden und mit der folgenden XPath-Abfragezeichenfolge suchen:

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

• Um nach einem untergeordneten Knoten von cq:editConfig zu suchen, können Sie z. B. nach cq:dropTargets suchen, der vom Typ cq:DropTargetConfig ist. Sie können das Tool "Abfrage"in der "CRXDE Lite"verwenden und mit der folgenden XPath-Abfragezeichenfolge suchen:

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

Komponenten-Platzhalter

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 Seiten-Editor (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 cq:EditConfig-Eigenschaften

cq:actions

Die Eigenschaft cq:actions ( String array) definiert eine oder mehrere Aktionen, die für die Komponente ausgeführt werden können. Folgende Werte stehen für die Konfiguration zur Verfügung:

Die folgende Konfiguration fügt eine Bearbeitungsschaltfläche, einen Abstand, eine Lösch- und eine Einfügungsschaltfläche zu der Bearbeitungsleiste der Komponente hinzu:

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

Die folgende Konfiguration fügt den Text „Inherited Configurations from Base Framework“ (Vom Basis-Framework geerbte Konfigurationen) zur Bearbeitungsleiste der Komponente hinzu:

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

cq:layout (nur klassische Benutzeroberfläche)

Die Eigenschaft cq:layout ( String) definiert, wie die Komponente in der klassischen Benutzeroberfläche bearbeitet werden kann. Die folgenden Werte sind verfügbar:

Die folgenden Konfigurationen fügen eine Bearbeitungsschaltfläche zur Bearbeitungsleiste der Komponente hinzu:

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

cq:dialogMode (nur klassische Benutzeroberfläche)

Sie können die Komponente mit einem Dialogfeld „Bearbeiten“ verknüpfen. Die Eigenschaft cq:dialogMode ( String) definiert, wie das Komponentendialogfeld in der klassischen Benutzeroberfläche geöffnet wird. Die folgenden Werte sind verfügbar:

Die folgende Konfiguration definiert eine Bearbeitungsleiste mit einer Bearbeitungsschaltfläche und einem unverankerten Dialogfeld:

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

cq:emptyText

Die Eigenschaft cq:emptyText ( String) definiert Text, der angezeigt wird, wenn kein visueller Inhalt vorhanden ist. Standardwert ist: Drag components or assets here.

cq:inherit

Die cq:inherit -Eigenschaft ( boolean) definiert, ob fehlende Werte von der Komponente übernommen werden, von der sie erbt. Standardwert ist false.

dialogLayout

Die Eigenschaft dialogLayout legt fest, wie ein Dialogfeld standardmäßig geöffnet werden soll.

• Der Wert fullscreen öffnet das Dialogfeld im Vollbildmodus.
• Bei einem leeren Wert oder einer fehlenden Eigenschaft wird das Dialogfeld standardmäßig normal geöffnet.
• Hinweis: Benutzer können den Vollbildmodus jederzeit innerhalb des Dialogfelds aktivieren.
• Gilt nicht für die klassische Benutzeroberfläche.

Konfigurieren mit untergeordneten cq:EditConfig-Knoten

cq:dropTargets

Der Knoten cq:dropTargets (Knotentyp nt:unstructured) definiert eine Liste von Ablagezielen, die eine Ablage aus einem Asset akzeptieren können, das aus der Inhaltssuche gezogen wurde. Er dient als Sammlung von Knoten des Typs cq:DropTargetConfig.

Jeder untergeordnete Knoten des Typs cq:DropTargetConfig definiert ein Ablageziel in der Komponente. Der Knotenname ist wichtig, da er im JSP wie folgt verwendet werden muss, um den CSS-Klassennamen zu erzeugen, der dem DOM-Element zugewiesen wird, das das effektive Ablageziel ist:

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

Der <drag and drop prefix> wird durch die Java-Eigenschaft definiert:

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

Beispielsweise wird der Klassenname wie folgt in der JSP der Download-Komponente definiert
( /libs/foundation/components/download/download.jsp), wobei file der Knotenname des Ablageziels in der Bearbeitungskonfiguration der Download-Komponente ist:

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

Der Knoten des Typs cq:DropTargetConfig muss die folgenden Eigenschaften aufweisen:

Die folgende Konfiguration wird aus der Download-Komponente übernommen. Sie ermöglicht es, dass jedes Asset (der MIME-Typ kann jeder beliebige String sein) aus der Gruppe media vom Content Finder in der Komponente abgelegt werden kann. Nach der Ablage wird die Komponenteneigenschaft fileReference aktualisiert:

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

cq:actionConfigs (nur klassische Benutzeroberfläche)

Der Knoten cq:actionConfigs (Knotentyp nt:unstructured) definiert eine Liste neuer Aktionen, die an die Liste angehängt werden, die durch die Eigenschaft cq:actions definiert wird. Jeder untergeordnete Knoten von cq:actionConfigsdefiniert eine Aktion, indem er ein Widget definiert.

Die folgende Beispielkonfiguration definiert eine neue Schaltfläche (mit einem Trennzeichen für die klassische Benutzeroberfläche):

• ein Trennzeichen, definiert durch den xtype tbseparator;

  • Dies wird nur von der klassischen Benutzeroberfläche verwendet.
  • Diese Definition wird von der Touch-optimierten Benutzeroberfläche ignoriert, weil xtypes ignoriert werden (und Trennzeichen unnötig sind, da die Aktionssymbolleiste in der Touch-optimierten Benutzeroberfläche anders aufgebaut ist).

• eine Schaltfläche mit dem Namen Kommentare verwalten, über die die Handler-Funktion CQ_collab_forum_openCollabAdmin() ausgeführt wird.

<jcr:root 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="[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>

cq:formParameters

Der Knoten cq:formParameters (Knotentyp nt:unstructured) definiert zusätzliche Parameter, die zum Dialogfeldformular hinzugefügt werden. Jede Eigenschaft wird einem Formularparameter zugeordnet.

Die folgende Konfiguration fügt einen Parameter namens name mit dem Wert photos/primary zum Dialogfeldformular hinzu:

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

cq:inplaceEditing

Der Knoten cq:inplaceEditing (Knotentyp cq:InplaceEditingConfig) definiert eine Konfiguration zur Bearbeitung im Kontext für die Komponente. Er kann die folgenden Eigenschaften aufweisen:

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

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

cq:listeners

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 angepassten Implementierung implementiert werden. Beispiel (hier ist project.customerAction eine statische Methode):

afteredit = "project.customerAction"

Das folgende Beispiel entspricht der REFRESH_INSERTED-Konfiguration:

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