Anpassen und Erweitern von Inhaltsfragmenten customizing-and-extending-content-fragments

Erstellen und Verwalten von Inhaltsfragmenten und Seitenbearbeitung mit Inhaltsfragmenten.

Weitere Informationen zu Standard-Assets finden Sie unter Verwalten von Assets und Anpassen und Erweitern von Assets.

Inhaltsfragmentmodelle:

• Diese dienen zum Definieren von Inhaltsfragmenten mit strukturierten Inhalten.
• Inhaltsfragmentmodelle definieren die Struktur eines Inhaltsfragments, wenn dieses erstellt wird.
• Ein Fragment verweist auf das Modell. Änderungen am Modell können sich daher auf alle abhängigen Fragmente auswirken.
• Modelle werden anhand von Datentypen erstellt.
• Funktionen zum Hinzufügen neuer Varianten müssen das Fragment entsprechend aktualisieren.

Inhaltsfragmentvorlagen:

• wird zum Definieren von einfachen Inhaltsfragmenten verwendet.
• Vorlagen definieren die (grundlegende, textbasierte) Struktur eines Inhaltsfragments, wenn dieses erstellt wird.
• Die Vorlage wird beim Erstellen des Fragments in dieses kopiert. Weitere Änderungen an der Vorlage werden daher nicht für bereits vorhandene Fragmente übernommen.
• Funktionen zum Hinzufügen neuer Varianten müssen das Fragment entsprechend aktualisieren.
• Inhaltsfragmentvorlagen funktionieren anders als die anderer Vorlagenmechanismen im AEM-Ökosystem (z. B. Seitenvorlagen). Daher sollten sie separat berücksichtigt werden.
• Wenn der MIME-Typ eines Inhalts auf einer Vorlage basiert, wird er für den tatsächlichen Inhalt verwaltet. Folglich kann jedes Element und jede Variante einen anderen MIME-Typ aufweisen.

Alle Inhalte werden im Knoten jcr:content/data des Assets gespeichert:

• Die Elementdaten werden im primären Unterknoten gespeichert:
  jcr:content/data/master

• Varianten werden in einem Unterknoten gespeichert, der den Namen der Variante hat:
  z. B. jcr:content/data/myvariation

• Die Daten der einzelnen Elemente werden im entsprechenden Unterknoten als Eigenschaft mit dem Elementnamen gespeichert:
  Das Inhaltselement text wird beispielsweise mit der Eigenschaft text in jcr:content/data/master gespeichert.

Metadaten und verknüpfte Inhalte werden unter jcr:content/metadata gespeichert.
Eine Ausnahme bilden der Titel und die Beschreibung, die nicht als Metadaten im herkömmlichen Sinne gelten und in jcr:content gespeichert werden.

Alle nicht inhaltsbezogenen Daten in einem Fragment (wie Titel, Beschreibung, Metadaten, Struktur) werden ausschließlich im Haupt-Asset verwaltet.

Der Inhalt des ersten Elements eines Fragments wird der ursprünglichen Ausgabedarstellung des Haupt-Assets zugeordnet.

• Die Varianten (falls vorhanden) des ersten Elements werden anderen Ausgabedarstellungen des Haupt-Assets zugeordnet.

Zusätzliche Elemente (falls vorhanden) werden Teil-Assets des Haupt-Assets zugeordnet.

• Der Hauptinhalt dieser zusätzlichen Elemente wird dem ursprünglichen Ausgabeformat des jeweiligen Unter-Assets zugeordnet.
• Andere Varianten (falls zutreffend) zusätzlicher Elemente werden anderen Ausgabeformaten der jeweiligen Unter-Assets zugeordnet.

Die Komponente verwendet die fragmentPath-Eigenschaft für Verweise auf das tatsächliche Inhaltsfragment. Die fragmentPath-Eigenschaft wird wie ähnliche Eigenschaften anderer Asset-Typen gehandhabt, beispielsweise wenn das Inhaltsfragment zu einem anderen Speicherort verschoben wird.

Mit der Komponente können Sie die Variante auswählen, die angezeigt werden soll.

Außerdem kann eine Reihe von Absätzen ausgewählt werden, um die Ausgabe zu beschränken, z. B. für die Ausgabe in mehreren Spalten.

Die Komponente lässt auch Zwischeninhalte zu:

• Hier können Sie mit der Komponente andere Assets (Bilder) zwischen den Absätzen des referenzierten Fragments platzieren.

• Bei Zwischeninhalten müssen Sie:

  • beachten, dass Verweise möglicherweise instabil sind. Bei der Seitenbearbeitung hinzugefügte Zwischeninhalte haben keine feste Beziehung zu dem Absatz, neben dem sie platziert werden; es wird ein neuer Absatz (im Inhaltsfragment-Editor) eingefügt, bevor der Zwischeninhalt die relative Position verlieren kann.
  • zusätzliche Parameter (wie Varianten und Absatzfilter) berücksichtigen, um falsch-positive Suchergebnisse zu vermeiden.

Ressourcentypen
Es kann eine Liste von sling:resourceTypes angegeben werden, um zu definieren, welche Komponenten zum Rendern der Inhaltsfragmente verwendet werden sollen und worauf die Hintergrundverarbeitung angewendet werden soll.

Verweiseigenschaften Eine Liste der konfigurierbaren Eigenschaften, die angeben, wo der Verweis auf das Fragment für die entsprechende Komponente gespeichert werden soll.

Der Name der Eigenschaft, die das Rendern der Elemente definiert, muss element oder elementNames lauten.

Der Name der Eigenschaft, die das Rendern der Variante definiert, muss variation oder variationName lauten.

Falls die Ausgabe mehrerer Elemente (durch Verwendung von elementNames zur Angabe mehrerer Elemente) unterstützt wird, wird der tatsächliche Anzeigemodus durch die displayMode-Eigenschaft definiert:

• Falls der Wert singleText lautet (und nur ein Element konfiguriert ist), wird das Element als Text mit Zwischeninhalt und Layout-Unterstützung gerendert. Dies ist die Standardeinstellung für Fragmente, für die nur ein einzelnes Element gerendert wird.
• In allen anderen Fällen wird ein weitaus einfacherer Ansatz (eine Art „Formularansicht“) verwendet, bei dem kein Zwischeninhalt unterstützt, sondern das Fragment im Ist-Zustand gerendert wird.

Falls das Fragment für displayMode == singleText (implizit oder explizit) gerendert wird, müssen auch folgende zusätzlichen Eigenschaften berücksichtigt werden:

• paragraphScope definiert, ob alle Absätze oder nur ein Absatzbereich gerendert werden sollen (Werte: all oder range).

• Falls paragraphScope == range, definiert die paragraphRange-Eigenschaft den Absatzbereich, der gerendert werden soll.

Übersetzungen

Inhaltsfragmente sind vollständig mit dem AEM-Übersetzungs-Workflow integriert. Auf Architekturebene bedeutet dies:

• Die einzelnen Übersetzungen eines Inhaltsfragments sind separate Fragmente, z. B.:

  • sie befinden sich unter verschiedenen Sprachstämmen:

    /content/dam/<path>/en/<to>/<fragment>

    im Vergleich zu

    /content/dam/<path>/de/<to>/<fragment>

  • sie verwenden jedoch genau denselben relativen Pfad unterhalb des Sprachstamms:

    /content/dam/<path>/en/<to>/<fragment>

    im Vergleich zu

    /content/dam/<path>/de/<to>/<fragment>

• Außer den regelbasierten Pfaden besteht keinerlei Verbindung zwischen den unterschiedlichen Sprachversionen von Inhaltsfragmenten. Sie werden als zwei separate Fragmente behandelt, obwohl die Benutzeroberfläche Funktionen zum Navigieren zwischen den Sprachvarianten beinhaltet.

Metadatenschemata

• Inhaltsfragmente verwenden Metadatenschemata (wieder), die mit Standard-Assets definiert werden können.

• CFM bietet ein eigenes, spezifisches Schema:

  /libs/dam/content/schemaeditors/forms/contentfragment

  dieses kann bei Bedarf erweitert werden.

• Das entsprechende Schemaformular ist mit dem Fragmenteditor integriert.

Fragmentvorlage (FragmentTemplate)

Verwenden Sie FragmentTemplate.createFragment() zum Erstellen eines neuen Fragments.

Resource templateOrModelRsc = resourceResolver.getResource("...");
FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");

Diese Schnittstelle steht für:

• ein Inhaltsfragmentmodell oder eine Inhaltsfragmentvorlage, aus dem bzw. der Sie ein Inhaltsfragment erstellen können,
• und (nach dem Erstellen) die Strukturdaten des Fragments.

Diese Daten können Folgendes beinhalten:

• Zugriff auf grundlegende Daten (Titel, Beschreibung)

• Zugriff auf Vorlagen/Modelle für die Elemente des Fragments:

  • Auflisten von Elementvorlagen
  • Abrufen von Strukturdaten für ein bestimmtes Element
  • Zugriff auf die Elementvorlage (siehe ElementTemplate)

• Zugriff auf Vorlagen für die Varianten des Fragments:

  • Auflisten von Variantenvorlagen
  • Abrufen von Strukturdaten für eine bestimmte Variante
  • Zugriff auf die Variantenvorlage (siehe VariationTemplate)

• Abrufen anfänglich zugeordneter Inhalte

Schnittstellen, die für wichtige Daten stehen:

• ElementTemplate

  • Abrufen grundlegender Daten (Name, Titel)
  • Abrufen anfänglicher Elementinhalte

• VariationTemplate

  • Abrufen grundlegender Daten (Name, Titel, Beschreibung)

Inhaltsfragment  (ContentFragment)

Mit dieser Schnittstelle können Sie abstrakt mit einem Inhaltsfragment arbeiten.

Die Schnittstelle bietet folgende Möglichkeiten:

• Verwalten grundlegender Daten (z. B. Abrufen von Namen, Abrufen/Festlegen von Titel/Beschreibung)

• Zugriff auf Metadaten

• Zugriff auf Elemente:

  • Auflisten von Elementen

  • Abrufen von Elementen nach Name

  • Erstellen neuer Elemente (siehe Einschränkungen)

  • Zugriff auf Elementdaten (siehe ContentElement)

• Auflisten der für das Fragment definierten Varianten

• Globales Erstellen neuer Varianten

• Verwalten zugeordneter Inhalte:

  • Auflisten von Sammlungen
  • Hinzufügen von Sammlungen
  • Entfernen von Sammlungen

• Zugreifen auf das Modell oder die Vorlage des Fragments

Folgende Schnittstellen stehen für die Hauptelemente eines Fragments:

• Inhaltselement (ContentElement)

  • Abrufen grundlegender Daten (Name, Titel, Beschreibung)

  • Abrufen/Festlegen von Inhalten

  • Zugriff auf Varianten eines Elements:

    • Auflisten von Varianten
    • Abrufen von Varianten nach Name
    • Erstellen neuer Varianten (siehe Einschränkungen)
    • Entfernen von Varianten (siehe Einschränkungen)
    • Zugriff auf Variantendaten (siehe ContentVariation)

  • Tastaturbefehl zum Auflösen von Varianten (Anwenden zusätzlicher implementierungsspezifischer Ausweich-Logik, falls die angegebene Variante für ein Element nicht verfügbar ist)

• Inhaltsvariante (ContentVariation)

  • Abrufen grundlegender Daten (Name, Titel, Beschreibung)
  • Abrufen/Festlegen von Inhalten
  • Einfache Synchronisierung basierend auf den zuletzt geänderten Informationen

Alle drei Schnittstellen (ContentFragment, ContentElement, ContentVariation) erweitern die Versionable-Schnittstelle durch zusätzliche, für Inhaltsfragmente erforderliche Versionierungsfunktionen:

• Erstellen neuer Versionen des Elements
• Auflisten der Versionen des Elements
• Abrufen des Inhalts einer spezifischen Version des versionierten Elements

ContentFragment kann angepasst werden an:

• Resource – die zugrunde liegende Sling-Ressource. Beachten Sie, dass beim direkten Aktualisieren der zugrunde liegenden Resource das ContentFragment-Objekt neu erstellt werden muss.

• Asset – die DAM-Asset-Abstrahierung, die für das Inhaltsfragment steht. Beachten Sie, dass beim direkten Aktualisieren des Asset das ContentFragment-Objekt neu erstellt werden muss.

ContentElement kann angepasst werden an:

• ElementTemplate – für den Zugriff auf die Strukturdaten des Elements.

FragmentTemplate kann angepasst werden an:

• Resource – die Resource, die das Modell, auf das verwiesen wird, oder die ursprüngliche Vorlage, die kopiert wurde, bestimmt.

  • An der Resource vorgenommene Änderungen werden nicht automatisch für die FragmentTemplate übernommen.

Resource kann angepasst werden an:

• ContentFragment
• FragmentTemplate

Die API wird implementiert, um die von der Benutzeroberfläche unterstützte Funktionalität bereitzustellen.

Die gesamte API ist so konzipiert, dass Änderungen nicht automatisch persistent gespeichert werden (es sei denn, dies ist anders in der Java-Dokumentation der API angegeben). Daher müssen Sie immer den Ressourcenkonfliktlöser der entsprechenden Anfrage (oder den tatsächlich verwendeten Konfliktlöser) festlegen.

Aufgaben, für die möglicherweise zusätzliche Arbeitsschritte erforderlich sind:

• Beim Erstellen/Entfernen neuer Elemente wird die Datenstruktur einfacher Fragmente (basierend auf einer Fragmentvorlage) nicht aktualisiert.

• Beim Erstellen neuer Varianten auf Basis von ContentElement wird die Datenstruktur nicht aktualisiert (beim globalen Erstellen auf Basis von ContentFragment wird sie jedoch aktualisiert).

• Beim Entfernen vorhandener Varianten wird die Datenstruktur nicht aktualisiert.

filter.xml

filter.xml für die Inhaltsfragmentverwaltung ist so konfiguriert, dass es sich nicht mit dem Hauptinhaltspaket für Assets überschneidet.

Starten einer Sitzung

• Eine neue Version des Inhaltsfragments wird erstellt.
• Das automatische Speichern wird gestartet.
• Cookies werden festgelegt. Diese definieren das derzeit bearbeitete Fragment und den Status „offene Bearbeitungssitzung“.

Beenden einer Sitzung

• Das automatische Speichern wird beendet.

• Beim Speichern:

  • Die Daten zur letzten Änderung werden aktualisiert.
  • Cookies werden entfernt.

• Beim Zurücksetzen:

  • Die Version des Inhaltsfragments, die beim Starten der Bearbeitungssitzung erstellt wurde, wird wiederhergestellt.
  • Cookies werden entfernt.

Bearbeiten

• Alle Änderungen (die automatische Speicherung eingeschlossen) werden am aktiven Inhaltsfragment vorgenommen, nicht in einem separaten, geschützten Bereich.
• Daher werden diese Änderungen sofort auf den AEM-Seiten widergespiegelt, die auf das entsprechende Inhaltsfragment verweisen.

Aufrufen einer Seite

• Überprüfen Sie anhand des entsprechenden Cookies, ob bereits eine Bearbeitungssitzung vorhanden ist.

  • Falls ja, vergewissern Sie sich, dass die Bearbeitungssitzung für das derzeit bearbeitete Inhaltsfragment gestartet wurde.

    • Falls ja, stellen Sie die Sitzung wieder her.
    • Falls nicht, versuchen Sie, die Bearbeitung des zuvor bearbeiteten Inhaltsfragments abzubrechen, und entfernen Sie die Cookies (anschließend ist keine Bearbeitungssitzung mehr aktiv).

  • Falls keine Bearbeitungssitzung vorhanden ist, warten Sie, bis die Benutzerin oder der Benutzer die erste Änderung vorgenommen hat (siehe unten).

• Überprüfen Sie, ob bereits eine Seite auf das Inhaltsfragment verweist, und zeigen Sie die Daten an, falls zutreffend.

Ändern von Inhalten

• Jedes Mal, wenn ein Benutzer Inhalte ändert und keine Bearbeitungssitzung vorhanden ist, wird eine Bearbeitungssitzung erstellt (siehe Starten einer Sitzung).

Verlassen einer Seite

• Falls eine Bearbeitungssitzung vorhanden ist und die Änderungen nicht persistent gespeichert wurden, wird ein Modal-Bestätigungsdialogfeld angezeigt, um den Benutzer über potenziell verloren gegangene Daten zu benachrichtigen und es ihm zu ermöglichen, auf der Seite zu bleiben.

Knoten: <*conf-root*>/settings/dam/cfm/jcr:content

Eigenschaftsname: autoSaveInterval

Typ: Long

Standard: 600 (10 Minuten); wird definiert in /libs/settings/dam/cfm/jcr:content

Knoten: /conf/global/settings/dam/cfm/jcr:content

Eigenschaftsname: autoSaveInterval

Typ: Long

Wert: 300 (5 Minuten entsprechen 300 Sekunden)