Online Dokumentation FirstSpirit V4.2

Startseite / Weiterführende Themen / Dokumentengruppen

Dokumentengruppen

Mit Hilfe von Dokumentengruppen können mehrere unabhängige Seiten zu einer Einheit zusammengefasst und damit die hierarchische Struktur, die in der Struktur-Verwaltung definiert wird, aufgehoben werden. Auf diese Weise können beispielsweise Teile des Internetauftritts zu einem in sich geschlossenen, linearen Dokument mit separatem Layout zusammengefasst werden. Ein häufiger Anwendungsfall sind PDF-Dokumente, die aus Seiten der Inhalte-Verwaltung generiert werden, inklusive Titelseite, Inhaltsverzeichnis und Kapitelnummerierung.

Verwenden von Dokumentengruppen

Für die Verwendung der Dokumentengruppen-Funktionalität muss eine entsprechende Lizenz vorliegen. Dazu muss der Parameter license.DOCUMENTGROUP der Lizenz (z.B. einsehbar im FirstSpirit Server Monitoring, Menüpunkt "FirstSpirit – Konfiguration – Lizenz") auf den Wert 1 gesetzt sein.

Weitere Informationen zur Konfiguration siehe FirstSpirit Handbuch für Entwickler (Grundlagen), Kapitel "Dokumentengruppen" und FirstSpirit Handbuch für Administratoren.

Im FirstSpirit JAVAclient werden Dokumentengruppen in der Struktur-Verwaltung angelegt und verwaltet.

Verwendung von Systemobjekten

Über sogenannte Systemobjekte kann innerhalb der Vorlagen auf Informationen, Daten und Objekte zugegriffen werden. Systemobjekte sind immer kontextabhängig. Innerhalb des Generierungskontextes stehen einige spezifische Systemobjekte zur Verfügung, mit der die Erzeugung von Dokumenten aus Dokumentengruppen gesteuert werden kann.

Folgende Systemobjekte können für Dokumentengruppen verwendet werden:

Verwendung von Kontextvariablen

Neben den Systemobjekten existieren weitere spezifische Kontextvariablen für das Arbeiten mit Dokumentengruppen. Bei diesen Kontextvariablen handelt es sich um benutzerspezifische Variablen, mit denen das Erscheinungsbild jedes Knotens einer Dokumentengruppe beeinflusst werden kann, d.h. es werden Fragmente vor oder nach einem Knoten ergänzt.

PREFIX: Diese Variable bewirkt, dass der nachfolgende Inhalt vor jedem Knoten eingeblendet wird.
SUFFIX: Diese Variable bewirkt, dass der nachfolgende Inhalt nach jedem Knoten eingeblendet wird.

Für Menüebenen werden Inhalte über die Variable SUFFIX erst nach dem letzten Kindknoten der Menüebene eingeblendet.

Verwendungsmöglichkeiten der beiden Variablen werden im Folgenden erläutert.

Anwendungsbeispiele

1. Beispiel: Kapitelüberschriften

Eine einfache Möglichkeit Kapitelüberschriften zu realisieren, besteht in der Verwendung der seitenspezifischen Kontextvariable PREFIX.

Mithilfe dieser Variable können FirstSpirit-Ausdrücke vor dem eigentlichen Inhalt jeder Seitenreferenz bzw. Menüebene definiert werden:

<CMS_HEADER>
</CMS_HEADER>
$CMS_SET(PREFIX)$
  <br />
  <hr />
  <h$CMS_VALUE(#docNode.depth)$>
    Kapitel&nbsp;$CMS_VALUE(#docNode.chapter)$&nbsp;
    $CMS_IF(!#docNode.label.isEmpty)$
      <a name="$CMS_VALUE(#docNode.label.convert2)$">
        $CMS_VALUE(#docNode.label.convert2)$
      </a>
    $CMS_END_IF$
  </h$CMS_VALUE(#docNode.depth)$>
  <hr />
$CMS_END_SET$

Über PREFIX wird hier der Aufbau der Kapitelüberschrift inklusive Anker für das Inhaltsverzeichnis definiert.

Das Systemobjekt #docNode wird dazu verwendet, die jeweiligen Informationen des jeweils aktuellen Elements der Dokumentengruppe auszulesen.

2. Beispiel: Inhaltsverzeichnis

Das Inhaltsverzeichnis wird in der Regel einmalig am Beginn eines Dokuments benötigt. Das unten angegebene Vorlagenfragment sollte daher in die Startvorlage übernommen werden:

<!-- Headline -->
<h1>
  <a name="summary"></a>
  $CMS_IF(#global.language.abbreviation == "DE")$
    &Uuml;bersicht
  $CMS_ELSE$
    Summary
  $CMS_END_IF$
  <br />
</h1>

<!-- Recursive loop -->
$CMS_SET(renderEntry)$
  <!-- All children (same level) -->
  $CMS_FOR(child, entries)$
    <!-- Indent -->
    $CMS_FOR(void, [0..(child.depth - 1)])$
        &nbsp;&nbsp;&nbsp;
    $CMS_END_FOR$

    <!-- Chapter -->
    $CMS_VALUE(child.chapter)$
    &nbsp;
    <!-- Label -->
    $CMS_IF(!child.label.isEmpty)$
      <a href="#$CMS_VALUE(child.label.convert2)$">
        $CMS_VALUE(child.label.convert2)$
      </a>
      <br />
    $CMS_END_IF$

    <!-- Recursive loop abort condition -->
    $CMS_IF(child.childs.size > 0)$
      $CMS_SET(entries, child.childs)$
      $CMS_VALUE(renderEntry)$
    $CMS_END_IF$
  $CMS_END_FOR$
$CMS_END_SET$

$CMS_SET(entries, #docGroup.childs)$
$CMS_VALUE(renderEntry)$
<br/>

Das Inhaltsverzeichnis wird eingeleitet durch die Überschrift (im Beispiel Absatz ).

Anschließend erfolgt die rekursive Ausführung (im Beispiel Absatz ).

Im Absatz  werden dann alle Kinder einer Ebene betrachtet und für jedes Element der Dokumentengruppe die Kapitelnummer sowie die zugehörige Beschriftung geholt. Dazu wird der Kapitelname (aus der Seitenreferenz bzw. dem Menünamen) ausgegeben und direkt mit einem Link versehen:

<a href="#$CMS_VALUE(child.label.convert2)$">
        $CMS_VALUE(child.label.convert2)$
      </a>

Die Anwendung der Funktion convert2 auf den Text der Seitengruppe bewirkt, dass nicht-HTML-konforme Zeichen durch die Konvertierungsregel in den Servereigenschaften (siehe FirstSpirit Handbuch für Administratoren) durch HTML-konforme Zeichen ersetzt werden. Zusätzlich werden HTML-eigene Zeichen (z.B. < (spitze öffnende Klammer) und > (spitze schließende Klammer)) quotiert. Dazu muss die Konvertierungsregel um das Zeichen " ergänzt werden.

Zuletzt erfolgt die Abbruchbedingung für die Rekursion (im Beispiel Absatz ).

Die Ausgabe könnte folgendermaßen aussehen:

Dokumentengruppe mit Nummerierung und Beschriftung

3. Beispiel: Sprung zum Inhaltsverzeichnis

Gerade bei längeren Dokumenten ist es häufig wünschenswert, dass am Ende eines Kapitels ein Sprung zum Inhaltsverzeichnis möglich wird.

Im folgenden Beispiel wird diese Funktionalität über ein seitenspezifisches SUFFIX erreicht. Es wird nach dem Rendern einer Seitenreferenz ausgegeben:

$CMS_SET(SUFFIX)$
  $CMS_IF(#docNode.isPageRef)$
    <a href="#summary">
      $CMS_IF(#global.language.abbreviation == "DE")$
        zur &Uuml;bersicht
      $CMS_ELSE$
        go to summary
      $CMS_END_IF$
    </a>
  $CMS_END_IF$
$CMS_END_SET$

4. Beispiel: Lokale Seitenreferenzen

Für die Aufbereitung von Verweisen in Dokumentengruppen kann es nützlich sein zu entscheiden, ob ein Link innerhalb der Dokumentengruppe bleibt oder aus der Dokumentengruppe herauszeigt, z.B. um einen internen PDF-Link zu erzeugen.

Dazu können die folgenden Ausdrücke verwendet werden:

$CMS_VALUE(#docGroup.contains("gewinnen_1"))$
$CMS_VALUE(#docGroup.contains(myVar))$

Dazu wird entweder die UID („Unified Identifier“) als String oder die Seitenreferenz direkt als „Object“ übergeben. Der Rückgabe-Wert des „.contains(...)“-Ausdrucks ist ein boolescher Wert, der z.B. für ein If-Statement verwendet werden kann.

Druckversion | Seitenanfang