Projektbezogene Kontexte

Projektweit sind folgende Kontexte in FirstSpirit für die Arbeit mit Variablen relevant:

Darüber hinaus gibt es eine Reihe weiterer Kontexte, die hier nicht dokumentiert werden, da nicht zugesichert werden kann, dass sie sich in zukünftigen FirstSpirit-Versionen nicht ändern. Das im Folgenden vorgestellte Konzept der Kontexte lässt sich aber prinzipiell auf alle Kontexte, die in FirstSpirit vorkommen können, übertragen.

Einige Kontexte haben keinen eindeutigen Bezeichner und können sich damit überschneiden. Weitere Informationen dazu siehe Seite Sonderfälle.

Einen Sonderfall stellen die Systemobjekte dar: einige stehen global im gesamten Projekt zur Verfügung (speziell das Systemobjekt #global), andere jeweils nur in bestimmten Vorlagentypen (das Systemobjekt #cs z. B. nur in Tabellenvorlagen). Die Verfügbarkeit und Verwendung der jeweiligen Systemobjekte ist detailliert im Kapitel Systemobjekte beschrieben.

Übersicht

Auf dieser Seite wird zunächst das grundlegende Konzept von Kontexten und der Verfügbarkeit von Variablen in diesen Kontexten vorgestellt:

• Wiederverwendung und Vererbung von Variablen
• Wo soll eine Variable definiert werden?
• Visualisierung von Kontextinformationen

Im Anschluss wird dargestellt, wie Variablen-Kontexte modifiziert werden können:

• Überschreiben von Variablen(werten)
• Variablen in höheren Kontexten verfügbar machen (Überladen)
  • Anwendungsbeispiel: Absätze einer Seite zählen
  • Anwendungsbeispiel: Absätze einer Seite zählen (incrementAndGet / AtomicInteger)
• Zugriff auf Variablen anderer Kontexte

Wiederverwendung und Vererbung

Die Kontexte sind hierarchisch angeordnet und ermöglichen dadurch eine Vererbung von Variablen von einem (höheren) Kontext in einen tieferen.

Unabhängig davon, wie ein Projekt aufgebaut ist (Seiten mit Absätzen, Seiten mit Datensätzen, Verwendung von Formatvorlagen usw.), sind in jedem Fall die Kontexte root, SITE-STORE und PAGE vorhanden. Die Kontexte section und cs sind nur dann verfügbar, wenn auch die entsprechenden Vorlagen (Absatz-, Tabellen-, Formatvorlagen usw.) verwendet werden.

Bei den standardmäßig verfügbaren Kontexten ist root der höchste Kontext, PAGE der niedrigste:

1. root
2. SITE-STORE
3. PAGE

Alle weiteren Kontexte liegen unterhalb von PAGE.

Variablen sind prinzipiell immer im gleichen Kontext und in allen tieferen Kontexten verfügbar. (Zur Verfügbarkeit von Variablen innerhalb einzelner Vorlagen siehe auch Seite Vorlagenbezogene Kontexte.)

Das heißt, Variablen, die in Generierungsaufträgen oder Projekteinstellungen definiert sind, sind z. B. im gesamten Projekt verfügbar, und so kann z. B. in Seiten- und Absatzvorlagen auf diese Variablen zugegriffen werden. In Absätzen und Formatvorlagen kann auf Variablen, die in Seiten gesetzt sind, zugegriffen werden usw.

Die folgende Abbildung zeigt die Verfügbarkeit von Variablen bis auf Absatzebene:

Auf Variablen, die in Absätzen gesetzt sind, kann man hingegen in Seiten standardmäßig nicht zugreifen, da der Seitenkontext höher liegt als der Absatzkontext (siehe Abbildung unten, Fall 2). Der Pfeil symbolisiert dabei die Vererbungsrichtung: In Fall 2 werden Variablen, die im Absatz definiert sind, nicht auf die Seite vererbt.

Ebenso kann eine Variable, die in einer Seitenvorlage definiert ist, nicht in einer anderen Seitenvorlage verwendet werden. Und auch der Wert, der über das Formular einer Seitenvorlage gespeichert wurde, kann nicht in einer anderen Seite (Instanz) derselben Seitenvorlage verwendet werden (siehe Abbildung unten, Fall 3).

Wo soll eine Variable definiert werden?

In Fall 3 der Abbildung müsste eine Variable, die in mehreren Seiten verfügbar sein soll, in einem höheren Kontext, z. B. im globalen Kontext, definiert werden.

Auf Werte, die in den Projekteinstellungen für eine Variable gesetzt sind, kann in einer Seitenvorlage z. B. zugegriffen werden, indem der Variablenname aus den Projekteinstellungen verwendet wird.

Beispiel
In den Projekteinstellungen ist die Variable ps_color gesetzt und hat dort den textuellen Wert #EFEFEF.
In einer Seitenvorlage kann auf diesen Wert zugegriffen werden, z. B. über

$CMS_VALUE(ps_color)$

Daher ist bei der Konzeption eines Projektes bzw. bei der Verwendung von Variablen zunächst zu berücksichtigen, in welchen Kontexten eine Variable verfügbar sein soll. Zwar müssen Variablen für Inhalte, die in mehreren Kontexten zur Verfügung stehen sollen, in einem höheren Kontext (z. B. root, SITE-STORE) angesiedelt werden, damit in allen untergeordneten Kontexten auf sie zugegriffen werden kann (z. B. PAGE, section). Um aber Überschneidungen bei der Variablendefinition zu vermeiden, sollten Variablen immer im tiefstmöglichen Kontext definiert werden.

Denn damit die Vererbung durchgängig über mehrere Kontexte hinweg im Projekt funktioniert, müssen die gewählten Variablennamen projektweit eindeutig sein, da es ansonsten zu Überschreibungen kommen kann (Namenskonflikt). Wird keine Wiederverwendung einer Variable in anderen (tieferen) Kontexten benötigt, kann in verschiedenen Kontexten auch derselbe Variablenname verwendet werden, ohne dass es zu Konflikten kommt.

Soll eine Variable in andere Kontexte gesetzt werden und damit die Verfügbarkeit ausgeweitet werden, kann dazu #global.context verwendet werden.

Speziell zum Unterschied von Variablen, die in Generierungsaufträgen, Projekteinstellungen und Menüebenen gesetzt werden können, siehe auch Seite Spezielle Variablen-Eigenschaften.

Visualisierung von Kontextinformationen

Welche Variablen für einen Kontext vorliegen, und welche Werte aktuell für diese Variable gespeichert sind, kann über den Aufruf

$CMS_VALUE(#global.dumpcontext)$

ausgegeben werden. Zusätzlich kann ein Trennzeichen zur Trennung der einzelnen Zeilen mit angegeben werden, z. B.

$CMS_VALUE(#global.dumpcontext("<br>"))$

Dieser Aufruf wird in den Ausgabe-Kanal der gewünschten Vorlage eingefügt und gibt dann die an der aktuellen Stelle verfügbaren Kontextinformationen aus.

Ist eine Variable in mehreren Kontexten zu finden, wird standardmäßig immer die Variable im tiefsten Kontext berücksichtigt. Durch Angabe des technischen Namen des gewünschten Kontexts und der gewünschten Variable kann auf den Wert der Variable in einem anderen Kontext zugegriffen werden.

Um z. B. den Wert der Variable „myVar“ des root-Kontexts auszugeben:

$CMS_VALUE(#global.context("root")["myVar"])$

Siehe dazu auch Abschnitt Zugriff auf Variablen anderer Kontexte.

Um z. B. aus einer Absatzvorlage heraus die Variable „myVar“ mit dem Wert 2 im PAGE-Kontext zu speichern:

$CMS_SET(#global.context("PAGE")["myVar"], 2)$

Siehe dazu auch Abschnitt Variablen in höheren Kontexten verfügbar machen.

Überschreiben von Variablen(werten)

Ein Wert, der für eine Variable in einem höheren Kontext gesetzt ist, kann in einem tieferen Kontext überschrieben werden. Dazu wird z. B. folgende Syntax verwendet:

$CMS_SET(ps_color, "#FF0000")$

Der neu definierte Wert gilt ab der Stelle, an der der oben genannte Aufruf erfolgt, und ist dann auch in allen tieferen Kontexten verwendbar.

Variablen in höheren Kontexten verfügbar machen (Überladen)

Standardmäßig ist eine Variable in FirstSpirit immer im gleichen Kontext sowie in tieferen Kontexten verfügbar.

In einigen Fällen kann es erforderlich sein, eine Variable in einen höheren Kontext zu setzen, um somit die Verfügbarkeit zu erhöhen. Dazu kann

#global.context("NAME")

verwendet werden. Über den Platzhalter NAME wird der Kontext mit dem technischen Namen, wie er in der oben dargestellten Tabelle in der mittleren Spalte („Kontext“) verwendet wird, angegeben. Der technische Name des betreffenden Kontexts kann auch über die Methode #global.dumpcontext ermittelt werden. Ist die Variable in mehreren Kontexten mit verschiedenen Werten definiert, wird standardmäßig immer die Variable im tiefsten Kontext berücksichtigt.

So kann z. B. eine Variable, die in einem Absatz definiert ist, und ihr Wert im Seitenkontext verfügbar gemacht werden. Dadurch kann auch in Absätzen einer Seite, die auf einer anderen Absatzvorlage basieren, auf die Variable zugegriffen werden. Die folgenden Grafiken stellen die Verwendung von #global.context schematisch dar:

Anwendungsbeispiel: Absätze einer Seite zählen
Auf diese Weise können beispielsweise die unterhalb einer Seite vorhandenen Absätze in der Inhalte-Verwaltung gezählt werden.
Im Ausgabekanal der Seitenvorlage wird dazu beispielsweise zunächst die Variable COUNTER mit dem Startwert 0 definiert:

$CMS_SET(COUNTER, 0)$

In der zugehörigen Absatzvorlage wird diese Variable in den Seitenkontext gesetzt und um 1 erhöht:

$CMS_SET(#global.context("PAGE")["COUNTER"], COUNTER + 1)$

Jeder Absatz, der auf dieser Absatzvorlage basiert und unterhalb der Seite mit der oben angegebenen Variablendefinition eingefügt wird, zählt nun die Variable COUNTER um 1 hoch.

In der Seitenvorlage kann die Variable dann wieder ausgegeben werden (nach der Ausgabe des Inhaltsbereichs):

$CMS_VALUE(#global.page.body("BEZEICHNER"))$
Anzahl der Absätze in dieser Seite: $CMS_VALUE(COUNTER)$

Die ausgegebene Zahl ist so hoch, wie die Anzahl der eingefügten Absätze.

Der Beispiel-Code der Seitenvorlage lautet also:

$CMS_SET(COUNTER, 0)$
$CMS_VALUE(#global.page.body("BEZEICHNER"))$
Anzahl der Absätze in dieser Seite: $CMS_VALUE(COUNTER)$

Der Beispiel-Code der Absatzvorlage:

$CMS_SET(#global.context("PAGE")["COUNTER"], COUNTER + 1)$

Verwendung von incrementAndGet
Alternativ kann die Methode .incrementAndGet mit der Klasse AtomicInteger verwendet werden.

Statt $CMS_SET(COUNTER, 0)$

wird dazu in der Seitenvorlage eingefügt:

$CMS_SET(COUNTER, class("java.util.concurrent.atomic.AtomicInteger").new)$

und in der Absatzvorlage:

$CMS_SET(gv_var, COUNTER.incrementAndGet)$

Mit dem Aufruf

Anzahl der Absätze in dieser Seite: $CMS_VALUE(COUNTER)$ 

kann in der Seitenvorlage wiederum die Anzahl der Absätze in der Seite, die auf der Absatzvorlage basieren, ausgegeben werden.

Der Beispiel-Code der Seitenvorlage lautet also:

$CMS_SET(COUNTER, class("java.util.concurrent.atomic.AtomicInteger").new)$
$CMS_VALUE(#global.page.body("BEZEICHNER"))$
Anzahl der Absätze in dieser Seite: $CMS_VALUE(COUNTER)$

Der Beispiel-Code der Absatzvorlage:

$CMS_SET(gv_var, COUNTER.incrementAndGet)$

Zugriff auf Variablen anderer Kontexte

Mit #global.context kann ebenso auf Variablen anderer Kontexte zugegriffen werden, und zwar über $CMS_VALUE(...)$.

Im folgenden Beispiel wird zunächst in einer Seitenvorlage eine Variable definiert (myVar) und dieser für verschiedene Kontexte verschiedene Werte zugewiesen:

$CMS_SET(#global.context("root")["myVar"], "Wert im root-Kontext")$
$CMS_SET(myVar, "Wert im PAGE-Kontext")$

Auf die unterschiedlichen Werte der Kontexte kann in der Seitenvorlage unter Angabe von #global.context wieder zugegriffen werden:

PAGE: $CMS_VALUE(myVar)$ </br>
root: $CMS_VALUE(#global.context("root")["myVar"])$