Dokumentengruppen
Mit Hilfe von Dokumentengruppen können mehrere unabhängige Seitenreferenzen 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 Struktur-Verwaltung generiert werden, inklusive Titelseite, Inhaltsverzeichnis und Kapitelnummerierung.
 |
Anders als die Inhalte normaler Seitenreferenzen, lassen sich die Inhalte einer Dokumentengruppe nicht im ContentCreator bearbeiten. Des Weiteren ist es im ContentCreator nicht möglich, eine Kopie einer Dokumentengruppe zu erstellen. |
Verwenden von Dokumentengruppen
Im FirstSpirit SiteArchitect werden Dokumentengruppen in der Struktur-Verwaltung angelegt und verwaltet.
Damit die Dokumentengruppen-Funktion genutzt werden kann, muss der Parameter license.DOCUMENTGROUP in der Lizenzdatei fs-license.conf den Wert „1“ haben.
Für weitere Informationen zur Verwendung von Dokumentengruppen siehe auch Neue Dokumentengruppe anlegen (→Handbuch FirstSpirit SiteArchitect) und Einstellungen für Dokumentengruppen (→Handbuch FirstSpirit SiteArchitect).
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.
Systemobjekte können überall da aufgerufen werden, wo auch Methoden-Aufrufe genutzt werden können. Jedes Systemobjekt beginnt mit dem Zeichen # und wird durch den jeweiligen Namen des Systemobjekts erweitert. Abhängig von der Art des Systemobjekts können unterschiedliche Methoden aufgerufen werden. Siehe dazu auch Kapitel Systemobjekte.
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.
Start- und Endvorlage
Diese Vorlagen enthalten nur den Rahmen, um ein gültiges Dokument des gewählten Vorlagensatzes zu erzeugen.
Beispiel: Startvorlage in HTML
<CMS_HEADER></CMS_HEADER>
<html>
<body>
Beispiel: Endvorlage in HTML
<CMS_HEADER></CMS_HEADER>
</body>
</html>
Bei Bedarf können an dieser Stelle auch Sonderfunktionen, wie z. B. die Erstellung eines „klickbaren“ Inhaltsverzeichnisses der Dokumentengruppe erfolgen.
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 $CMS_VALUE(#docNode.chapter)$
$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 verschiedenen Informationen (Tiefe im Baum, Nummerierung der Seitenreferenz bzw. Menüebene, Überschrift des Knotens) 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")$
Ü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)])$
$CMS_END_FOR$
<!-- Chapter -->
$CMS_VALUE(child.chapter)$
<!-- 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 <!-- Headline -->).
Anschließend erfolgt die rekursive Ausführung (im Beispiel Absatz <!-- Recursive loop -->).
Im Absatz <!-- Chapter --> 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 Konvertierungs-Regeln (→Dokumentation 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 <!-- Recursive loop abort condition -->).
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. Mithilfe der Variable SUFFIX können FirstSpirit-Ausdrücke nach dem eigentlichen Inhalt einer Seitenreferenz bzw. Menüebene definiert werden. Im Beispiel wird es nach dem Rendern einer Seitenreferenz ausgegeben:
$CMS_SET(SUFFIX)$
$CMS_IF(#docNode.isPageRef)$
<a href="#summary">
$CMS_IF(#global.language.abbreviation == "DE")$
zur Ü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-Verweis zu erzeugen.
Dazu können die folgenden Ausdrücke verwendet werden:
$CMS_VALUE(#docGroup.contains("einAusdruck"))$
$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.