Fragmente verwenden

Mit dem Fragment DAP können Fragmente aus einem Fragment-Projekt:

• in einem anderen Fragment-Projekt referenziert werden.
  Dort können die Fragmente auch bearbeitet und neue erstellt werden.
• in einem klassischen FirstSpirit-Projekt referenziert werden.
  Dort können sie gruppiert, strukturiert und miteinander in Relation gesetzt werden. Bei entsprechender Konfiguration können die referenzierten Fragmente auch im FirstSpirit ContentCreator bearbeitet werden.

Checkliste

Folgende Komponenten bzw. Konfigurationen sind erforderlich, wenn Sie die auf dieser Seite beschriebene Funktionalität nutzen möchten:

Komponente "FS_INDEX"

Zur Referenzierung von Fragmenten wird die Komponente „FS_INDEX“ verwendet.
Register „Formular“, Minimalkonfiguration:

<FS_INDEX name="fragments">
   <LANGINFOS>
     <LANGINFO lang="*" label="Fragment selection"/>
     <LANGINFO lang="DE" label="Fragment auswählen"/>
   </LANGINFOS>
   <SOURCE name="FirstSpiritFragmentAccess/FSFAConnector">
     <PROJECT remote="fragmentproject"/>
   </SOURCE>
</FS_INDEX>

Aktivierung der DAP-Funktionalität
Über das Tag SOURCE werden das FirstSpirit-Modul sowie die DataAccessPlugin-Komponente angegeben, und zwar über den Pflichtparameter name. In diesem Fall: „FirstSpiritFragmentAccess/FSFAConnector“.

Definition des Remote-Projekts
Das Projekt, aus dem die Fragmente ausgewählt werden sollen, muss über das Tag PROJECT angegeben werden. Über den Pflichtparameter remote muss dabei der symbolische Projektname des Remote-Projekts angegeben werden.

Darstellung der ausgewählten Fragmente
Über den Parameter viewMode kann der Anzeigemodus der Fragmente in der Eingabekomponente gesteuert werden. Die Anzeige greift dabei auf die Konfiguration des Registers „Schnipsel“ der Vorlage zurück, auf der das ausgewählte Fragment basiert.

• DETAILS (Standard): Anzeige der Informationen aus den Feldern „Miniaturansicht“, „Kennsatz“ und „Ausriss“.
• HEADERS: Anzeige der Informationen aus dem Feld „Kennsatz“.
• SYMBOLS: Anzeige der Informationen aus dem Feld „Miniaturansicht“.

Syntax-Beispiel:

<FS_INDEX name="fragments" useLanguages="no" viewMode="headers">...

Einschränkung auf Kategorien

Mit der oben dargestellten Minimalkonfiguration können alle Fragmente aus dem Projekt, das über das Attribut remote im Tag PROJECT spezifiziert ist, ausgewählt werden.
Um die Auswahl auf bestimmte Kategorien einzuschränken, kann die Konfiguration um das Tag CATEGORY erweitert werden. Der Name des betreffenden Inhalte-Ordners bzw. der betreffenden Seitenvorlage (im Remote-Projekt) wird über den Parameter uid spezifiziert (Referenzname):

<FS_INDEX name="fragments">
   <LANGINFOS>
     <LANGINFO lang="*" label="Fragment selection"/>
     <LANGINFO lang="DE" label="Fragment auswählen"/>
   </LANGINFOS>
   <SOURCE name="FirstSpiritFragmentAccess/FSFAConnector">
     <PROJECT remote="fragmentproject">
        <CATEGORY uid="teaser"/>
     </PROJECT>
   </SOURCE>
</FS_INDEX>

Es können auch mehrere Kategorien angegeben werden, z. B.

...
<PROJECT remote="fragmentproject">
     <CATEGORY uid="teaser"/>
     <CATEGORY uid="news"/>
</PROJECT>
...

Durch die Angabe des Tags CATEGORY wird gleichzeitig das Bearbeiten von referenzierten Fragmenten und Anlegen von neuen Fragmenten im Remote-Projekt aktiviert. Siehe dazu Abschnitt Bearbeiten und Erstellen von Fragmenten.

Beschränkung der Anzahl der auswählbaren Fragmente

Die Anzahl der Fragmente, die über die Komponente ausgewählt bzw. gespeichert werden können, kann über eine entsprechende Definition auf dem Register „Regel“ der Vorlage erfolgen, z. B.

<RULES>
  <RULE>
    <WITH>
       <NOT>
        <GREATER_THAN>
           <PROPERTY name="size" source="fragments"/>
           <NUMBER>1</NUMBER>
       </GREATER_THAN>
      </NOT>
    </WITH>
    <DO>
      <VALIDATION scope="RELEASE">
          <PROPERTY name="VALID" source="fragments"/>
          <MESSAGE lang="*" text="Only one element allowed"/>
          <MESSAGE lang="DE" text="Darf maximal ein Element enthalten."/>
      </VALIDATION>
    </DO>
  </RULE>
</RULES>

Über das Attribut source wird dabei die betreffende INDEX-Komponente (Register „Formular“) referenziert.

Zu weiteren Informationen zur Definition von Regeln siehe Seite Prüfen von Inhalten (Register "Regeln").

Einschränkung auf Varianten

Standardmäßig werden dem Redakteur alle zur Verfügung stehenden Varianten zur Auswahl angezeigt. Um die Auswahl auf bestimmte Variantendimension einzuschränken, kann die Konfiguration um das Tag VARIANT erweitert werden, z. B.

...
 <SOURCE name="FirstSpiritFragmentAccess/FSFAConnector">
 <PROJECT remote="fragments">
 <VARIANT name="language" value="EN"/>
 <VARIANT name="language" value="DE"/>
 <VARIANT name="device" value="Mobile"/>
 </PROJECT>
 </SOURCE>
...

VARIANT: Für jede Variantendimension, die der Redakteur auswählen können soll, muss eine VARIANT-Definition vorhanden sein.
Wird das Tag nicht angegeben, stehen alle Variantendimensionen zur Auswahl bereit.
Jede VARIANT-Definition erfordert die Angabe der Attribute name und value:

name: Über dieses Attribut muss der Bezeichner der Variantendimension, die zur Auswahl zur Verfügung stehen soll, angegeben werden.
Dabei handelt es sich um den Wert des name-Attributs der gewünschten Komponente in der Metadaten-Vorlage des Fragment-Projekts, aus dem die Auswahl per FragmentDAP erfolgt.
Für jede Variantendimension, die der Redakteur auswählen können soll, muss eine VARIANT-Definition mit passendem name-Attribut vorhanden sein.
Sind mehrere Variantendimensionen definiert, werden nur die Varianten angezeigt, die alle Bedingungen erfüllen (AND-Verknüpfung).

value: Über dieses Attribut kann die Auswahl auf bestimmte Typen einer Variantendimension eingeschränkt werden.
Dabei handelt es sich um den Wert des value-Attributs innerhalb von ENTRIES / ENTRY der gewünschten Komponente in der Metadaten-Vorlage des Fragment-Projekts, aus dem die Auswahl per FragmentDAP erfolgt.
Für jeden Typ einer Variantendimension, die der Redakteur auswählen können soll, muss eine VARIANT-Definition mit passendem name- und value-Attribut vorhanden sein.
Sind mehrere Typen einer Variantendimension definiert, werden alle Varianten angezeigt, die zu diesen Typen passen (OR-Verknüpfung).

Die Reihenfolge der VARIANT-Definitionen wirkt sich dabei auf die Reihenfolge aus, in der die Varianten im Auswahldialog angezeigt werden. Im obigen Beispiel werden immer Varianten der Dimension language vom Typ EN angezeigt (also englischsprachige Varianten).
Varianten (und damit das zugehörige Fragment), auf die die Varianteneinschränkungen nicht zutreffen, werden nicht angezeigt.

Diese Filterungsmöglichkeit kommt nur in einer entsprechend konfigurierten FS_INDEX-Komponente zum Tragen, nicht jedoch im „Fragment“-Report. Allerdings berücksichtigt die Anzeige im Report auch die Reihenfolge der VARIANT-Definitionen.

Verwendung im FragmentCreator

Auswahl von Fragmenten

Wurde die Minimalkonfiguration korrekt vorgenommen, erhält der Redakteur in einer Variante eine Möglichkeit, Fragmente auszuwählen:

Bearbeiten und Erstellen von Fragmenten

Mit dem Tag CATEGORY und der Angabe eines gültigen Werts für den Parameter uid (siehe Abschnitt Einschränkung auf Kategorien) können nicht nur Fragmente aus dem Remote-Projekt ausgewählt, sondern auch referenzierte bearbeitet und neue angelegt werden.

Wurde die Konfiguration korrekt vorgenommen, erhält der Redakteur in einer Variante eine Möglichkeit, referenzierte Fragmente zu bearbeiten und neue Fragmente zu erstellen.
Wurde nur eine Kategorie spezifiziert (Tag CATEGORY), wird über die Schaltfläche ein Fragment dieser Kategorie angelegt:

Wurden mehrere Kategorien spezifiziert, erhält der Redakteur einen Dialog zur Auswahl der gewünschten Kategorie.

Neue Fragmente werden in dem Remote-Projekt, das über das Attribut remote im Tag PROJECT spezifiziert ist, angelegt, und zwar mit der durch den Redakteur gewählten Vorlage. Im Beispiel wäre dies die Vorlage mit dem Referenznamen „teaser“. Die Fragmente werden im Bereich „Inhalte“ im Ordner mit dem Referenznamen „teaser“ angelegt.

Verwendung im SiteArchitect

Auswahl von Fragmenten

Im FirstSpirit ContentCreator können Fragmente mit der oben angegebenen Minimalkonfiguration ebenfalls ausgewählt werden.
Innerhalb der FS-INDEX-Komponente:

Passende Fragmente können auch aus dem entsprechenden Report ausgewählt werden:

Ausgabe von Fragmenten / Varianten (in FirstSpirit-Projekten)

Wie sich über eine wie oben beschrieben konfigurierte FS_INDEX-Komponente durch den Redakteur ausgewählte Fragmente / Varianten aus dem Fragment-Projekt in einem FirstSpirit-Projekt ausgeben lassen, siehe Seite Fragmente ausgeben.

Verwendung im ContentCreator

Auswahl von Fragmenten

Im FirstSpirit ContentCreator können Fragmente mit der oben angegebenen Minimalkonfiguration ebenfalls ausgewählt werden.
Innerhalb der FS-INDEX-Komponente:

Passende Fragmente können auch aus dem entsprechenden Report ausgewählt werden:

Bearbeiten von Fragmenten

Sollen Fragmente im ContentCreator bearbeitet werden können, muss die Web-Komponente „Fragment DAP for ContentCreator“ dem betreffenden Projekt in den Projekteigenschaften im Bereich „ContentCreator“ hinzugefügt werden („FirstSpirit ServerManager / Projekt-Eigenschaften / Web-Komponenten“, siehe dazu Seite Fragment Data Access Plugin (Fragment DAP).)

Im Bearbeitungsdialog mit der FS_INDEX-Komponente im ContentCreator wird ein entsprechendes Icon angezeigt:

Mit einem Klick wird das Formular aus dem FragmentCreator als MicroApp direkt im ContentCreator geöffnet und kann dort bearbeitet werden:

Anschließend kann der Redakteur das Formular (FragmentCreator) schließen (Icon X), die Änderungen werden automatisch gespeichert.

EasyEdit / Inline-Darstellung

Das „Bearbeiten“-Icon kann auch direkt in der Vorschau eingeblendet werden.
Dazu wird die betreffende FS_INDEX-Komponente mit einem editorId()-Aufruf in Verbindung mit dem Parameter externalReference ausgestattet. Dieser Parameter erwartet den Bezeichner von Referenzen, die in der FS_INDEX-Komponente gespeichert sind.

Beispiel:

<div$CMS_VALUE(editorId(editorName:"fragments"))$>
     $CMS_FOR(i, [0..fragments.identifiers.size-1])$
         $CMS_SET(fragment, fragments.values[i])$
         $CMS_SET(objectId, fragments.identifiers[i])$
         <div$CMS_VALUE(editorId(editorName:"fragments", externalReference: objectId))$>
             $CMS_FOR(variant, fragment.variants({"language": #global.language.abbreviation}))$
                 <b>$CMS_VALUE(variant.title)$</b><br>
                 $CMS_VALUE(variant.formData.text)$
              
             $CMS_END_FOR$
         </div>
     $CMS_END_FOR$
</div> 

• fragments: Bezeichner der betreffenden FS_INDEX-Komponente
• text: Bezeichner einer Eingabekomponente im gewählten Fragment
• objectId: repräsentiert einen Fragment-Eintrag der FS_INDEX-Komponente

Zu weiteren Informationen zur Methode editorId siehe auch Einsatz im Projekt (→Online Dokumentation FirstSpirit).

Ist die Vorlage korrekt konfiguriert und hat der Benutzer ausreichende Rechte, werden in der Vorschau direkt Bearbeiten-Icons an den ausgewählten Fragmenten angezeigt.

In Verwendung

Wird das Fragment von einem anderen Fragment referenziert, wird dies im FragmentCreator visualisiert, und zwar durch den Text „In Verwendung“.
Beim Löschen einer Variante wird ebenfalls in einer Dialog-Box darauf hingewiesen, dass Referenzen zu anderen Fragmenten bestehen.