Startseite / Vorlagenentwicklung / Variablen / Kontexte / Sonderfälle

Spezielle Variablen-Eigenschaften

Nachdem auf den vorangegangenen Seiten das Konzept der Variablen und Kontexte in FirstSpirit dargestellt wurde, werden im Folgenden Besonderheiten einiger Variablen und ihrer Definitionsstelle vorgestellt:

Variablen in Aufträgen, Projekteinstellungen und Menüebenen
- Variablen aus Aufträgen in Projekteinstellungen verfügbar machen
Variablen in Formatvorlagen
Variablen in Verweisvorlagen (z. B. im DOM-Editor)
Variablen in Globalen Inhalten

Variablen in Aufträgen, Projekteinstellungen und Menüebenen

Wie die Tabelle auf der vorherigen Seite zeigt, haben die Kontexte SITE-STORE und root Überschneidungspunkte.

In der Vorschau werden die Variablen dabei in folgender Reihenfolge ausgewertet:

Strukturvariablen
Variablen in Projekteinstellungen

Ist eine Variable in den Projekteinstellungen und in Menüebenen mit gleichem Namen definiert, ist sie sowohl im Kontext root (hier gilt der Wert, der über die Projekteinstellungen zugewiesen ist) als auch im Kontext SITE-STORE (hier gilt der Wert, der über die Menüebene zugewiesen ist) verfügbar. Ohne Anwendung von #global.context(...) (siehe Seite Projektbezogene Kontexte) wird in der Vorschau für die Variable der Wert, der über die Menüebene zugewiesen ist, ausgegeben, da standardmäßig die Variable im tiefsten Kontext berücksichtigt wird.

Bei Strukturvariablen ist darüber hinaus zu beachten, dass sie nur in der Vorschau von Seitenreferenzen (also Struktur-Verwaltung) angezeigt werden, nicht aber von Seiten (Inhalte-Verwaltung).

Auf einer generierten Seite können Strukturvariablen durch Auftragsvariablen überschrieben werden: Sind Auftragsvariablen gesetzt, werden sie auf der generierten Seite ausgelesen und überschreiben Variablen mit demselben Namen, die auf dem Wurzelknoten der Struktur-Verwaltung oder in den Projekteinstellungen definiert sind.

Es werden nur Variablen, die auf Wurzelknoten-Ebene der Struktur-Verwaltung definiert sind, überschrieben. In folgenden Fällen werden Strukturvariablen nicht von Auftragsvariablen mit demselben Namen überschrieben:
- Strukturvariablen, die auf Menüebenen definiert werden, die unterhalb des Wurzelknotens liegen,
- Strukturvariablen, die auf Wurzelknoten-Ebene definiert, aber auf einer darunterliegenden Menüebene verändert wurden.

Siehe dazu auch Seite Strukturvariablen.

Dies kann z. B. dazu genutzt werden, einen Unterschied zwischen der Vorschau und der generierten Website (bzw. Teile davon, Auftrag "Teilprojekt generieren") oder zwischen verschiedenen Generierungsaufträgen zu erzielen.

Sollen Variablen aus den Projekteinstellungen bei der Generierung ausgewertet werden, dürfen weder Auftrags- noch Strukturvariablen gesetzt sein.

Abb. 1: Struktur-Verwaltungs-Kontext versus Globaler Kontext (zum Vergrößern anklicken)

Beispiele für das Überschreiben von Variablen:
Ist in einer Menüebene, in den Projekteinstellungen und in einem Generierungsauftrag die Variable A mit jeweils unterschiedlichen Werten definiert, gilt in der Vorschau der Wert, der in der Struktur-Verwaltung, auf der generierten Seite der Wert, der im Auftrag definiert ist (allerdings nur für Werte, die auf der Wurzelknoten-Ebene der Struktur-Verwaltung definiert sind, Abb.1 : Fall 1 und 2).

Ist keine Auftragsvariable definiert, gilt auf der generierten Seite der Wert, der in der Struktur-Verwaltung definiert ist (Fall 3).

Nur wenn weder Auftrags- noch Strukturvariable definiert sind, wird der Wert der Variable aus den Projekteinstellungen verwendet (Fall 4).

Variablen aus Aufträgen in Projekteinstellungen verfügbar machen

In Generierungsaufträgen definierte Variablen (siehe auch Generierung ausführen (→Dokumentation für Administratoren)) stehen in den Projekteinstellungen standardmäßig nicht zur Verfügung.
Sie können folgendermaßen in der Projekteinstellungsseite verfügbar gemacht werden:

Variablen aus dem Generierungsauftrag in eine Map überführen (auf dem Ausgabe-Register der Vorlage für die Projekteinstellungen):

$CMS_SET(generationTaskVariables,{:})$ 
$CMS_IF(!#global.preview)$
      $CMS_FOR(var,#global.scheduleContext().getTask().getVariables())$
         $CMS_SET(void,generationTaskVariables.put(var.getKey(),var.getValue()))$
      $CMS_END_FOR$
$CMS_END_IF$

Der Zugriff ist dann möglich mittels

generationTaskVariables.<Name der Variable aus der Generierungsaktion des Auftrags>

also beispielsweise

$CMS_VALUE(generationTaskVariables.<Name der Variable aus der Generierungsaktion des Auftrags>)$

Die Variable sollte mit einem Falback-Wert abgesichert werden, für den Fall, dass die Variable in der Ausgabe nicht gesetzt ist, beispielsweise:

$CMS_VALUE(generationTaskVariables.target, default:"development")$

So wird entweder der Wert der Variable target aus der Auftrags-Generierungs-Aktion ausgegeben (siehe Abbildung) oder der String development (aus der Projekteinstellungsseiten-Vorlage), wenn die Variable in dem entsprechenden Auftrag nicht gesetzt wurde oder kein Auftrag verwendet wird (z. B. in der Vorschau).

Variablen in Formatvorlagen

Inhalte von Formatvorlagen oder Skripten können in anderen Vorlagentypen (z. B. Seiten- oder Absatzvorlagen) über die Anweisung $CMS_RENDER(...)$ in Kombination mit dem Parameter template bzw. script eingebunden werden, z. B.

$CMS_RENDER(template:"BEZEICHNER")$

Bei dem BEZEICHNER handelt es sich um das Kürzel der Formatvorlage bzw. des Skripts, welches eingebunden werden soll.

Setzen und Ausgeben von Variablen in Formatvorlagen
Aufgrund der Verfügbarkeit von Variablen in tieferen Kontexten, kann auch in Formatvorlagen z. B. auf Variablen, die in Seiten- oder Absatzvorlagen vorhanden sind, zugegriffen werden: Ist z. B. in einer Seitenvorlage die Variable gv_page definiert:

$CMS_SET(gv_page, "Variable im Seitenkontext")$                                                                                                             (Seitenvorlage)

kann auf diese in einer über den $CMS_RENDER(...)$-Aufruf in die Seitenvorlage eingebundenen Formatvorlage zugegriffen und so z. B. über

$CMS_VALUE(gv_page)$                                                                                                                                                           (Formatvorlage)

ausgegeben werden.

Wie bereits zuvor dargestellt, ist hier natürlich wichtig, die Variable gv_page vor dem Aufruf $CMS_RENDER(...)$ zu definieren

Variablen, die in Formatvorlagen definiert sind, sind hingegen standardmäßig nicht im (höheren) Seitenkontext verfügbar. Das heißt, auf Variablen, die in Formatvorlagen definiert sind, kann in Seitenvorlagen nicht zugegriffen werden. Die Ausgabe kann daher nur über die Formatvorlage selbst, nicht aber über die Seitenvorlage erfolgen.

Wird z. B. in einer Formatvorlage die Variable gv_form definiert

$CMS_SET(gv_form, "Variable im Formatvorlagen-Kontext")$                                                                                         (Formatvorlage)

kann diese nur über die Formatvorlage ausgegeben werden, z. B.

$CMS_VALUE(gv_form)$                                                                                                                                                           (Formatvorlage)

Um eine in einer Formatvorlage definierte Variable auch im Seitenkontext verfügbar zu machen, kann der $CMS_RENDER(...)$-Aufruf um den Parameter context:"this" ergänzt werden.

Hierbei ist allerdings zu beachten, dass auf diese Weise Variablen in einem anderem Kontext ungewollt überschrieben werden können.

Ist z. B. in einer Formatvorlage die Variable gv_form definiert:

$CMS_SET(gv_form, "Variable im Formatvorlagen-Kontext")$                                                                                         (Formatvorlage)

kann auf diese über folgenden $CMS_RENDER(...)$-Aufruf in der Seitenvorlage zugegriffen

$CMS_RENDER(template:"BEZEICHNER", context:"this")$                                                                                                  (Seitenvorlage)

und so z. B. über

$CMS_VALUE(gv_form)$                                                                                                                                                            (Seitenvorlage)

ausgegeben werden.

Das gleiche gilt natürlich auch für Absatzvorlagen und Skripte.

Variablen in Verweisen

Ein weiterer häufiger Anwendungsfall für geschachtelte Kontexte ist das Verwenden von Verweisvorlagen im DOM-Editor (CMS_INPUT_DOM).

Abb. 2: Kontexte in Verweisen

Standardmäßig erben Verweise in DOM-Editoren Variablen aus höheren Kontexten, d.h. Variablen, die beispielsweise zuvor in der Seite oder einem Absatz initialisiert wurden, in der / dem der DOM-Editor mit einer Verweisvorlage verwendet wird, können in der Verweisvorlage selbst verwendet werden. Abb. 2 zeigt schematisch die Gültigkeit von Variablen / Werten in Verweisvorlagen in einem DOM-Editor.

Dabei wird die Gültigkeit von Variablen, wenn sie im Formular oder im Vorlagensatz initialisiert werden, dargestellt:

pt_var_form: eine Variable, die im Formular einer Seitenvorlage initialisiert wurde
pt_var_out: eine Variable, die im Vorlagensatz einer Seitenvorlage initialisiert wurde (z. B. über $CMS_SET(...)$)
st_var_form: eine Variable, die im Formular einer Absatzvorlage, speziell in der Eingabekomponente CMS_INPUT_DOM initialisiert wurde
st_var_out: eine Variable, die im Vorlagensatz einer Absatzvorlage initialisiert wurde (z. B. über $CMS_SET(...)$)
link_var_form: eine Variable, die im Formular einer Verweisvorlage initialisiert wurde
link_var_out: eine Variable, die im Vorlagensatz einer Verweisvorlage initialisiert wurde

Es ist nicht ratsam, in der Verweisvorlage den Inhalt des DOM-Editors der Seite oder des Absatzes auszugeben, die / der den Verweis enthält, da so eine Endlosschleife entstünde (in Abb. 2: st_var_form, angedeutet durch die gestrichelte Linie).
Allgemein gilt, dass es niemals sinnvoll ist, den äußeren Kontext in einem inneren auszugeben.

Somit stehen Werte, die der Redakteur in einen Verweis eingegeben wird (in Abb. 2: link_var_form) standardmäßig nur im Kontext des Verweises zur Verfügung. Mit #global.context("NAME") können diese Werte auch im nächst höheren Absatz- bzw. Seitenkontext verfügbar gemacht werden:

$CMS_SET(#global.context("section")["link_var_form"],link_var_form)$

bzw.

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

Variablen innerhalb eines Verweises können wie auch für andere FirstSpirit-Objekte durch Verwendung von $CMS_SET(...)$ überschrieben werden. Dies gilt sowohl für Variablen, die als Bezeichner für Eingabekomponenten auf dem Formular-Register der Verweisvorlage verwendet, als auch für Variablen, die z. B. per $CMS_SET(...)$ in einem Vorlagensatz der Verweisvorlage definiert werden. Ein Anwendungsbeispiel hierfür kann eine Auto-Vervollständigung oder Auto-Korrektur z. B. für E-Mail-Adressen sein (siehe dazu auch das Beispiel für E-Mail-Verweise). Dabei wird zunächst geprüft, ob seitens des Redakteurs in die Eingabekomponente lt_reference eine E-Mail-Adresse mit dem erforderlichen „mailto:“ eingegeben wurde. Fehlt das „mailto:“, wird es automatisch ergänzt, z. B.

$CMS_IF(!lt_reference.startsWith("mailto:"))$
  $CMS_SET(lt_reference, "mailto:"+lt_reference)$
$CMS_END_IF$

Variablen in Globalen Inhalten

Abb. 3: Struktur von Globalen Inhalten

Inhalte einer Globalen Seite (und ggf. der in der Globalen Seite eingebundenen Absätze) wird in der gewünschten Vorlage mit $CMS_VALUE(#global.gca("BEZEICHNER"))$ ausgegeben werden. Dabei muss für den Platzhalter BEZEICHNER der Referenzname der auszugebenden Seite aus den Globalen Inhalten angegeben werden. An der Stelle des Aufrufs von $CMS_VALUE(#global.gca("BEZEICHNER"))$ wird der Inhalt der entsprechenden Vorlage eingefügt und der Kontext der Globalen Seite beginnt. Hier werden also Kontexte geschachtelt.

Abb. 2 zeigt vereinfacht die Struktur einer Seite mit Absatz in der Inhalte-Verwaltung („PS“) mit einer Seite und Absatz aus den Globalen Inhalten („GCA“). Auch hier kann man demnach von „äußeren“ Elementen (z. B. die Seite in der Inhalte-Verwaltung) und „inneren“ Elementen (z. B. der Absatz in den Globalen Inhalten) sprechen.

Abb. 4: Kontexte von Globalen Inhalten

Durch diese Schachtelung können sich Kontexte der Absätze überlappen oder überschreiben, da z. B. Absatz (PS) und Absatz (GCA) jeweils über einen Kontext mit dem Namen section verfügen. Seite (PS) und Seite (GCA) verfügen hingegen jeweils über einen eigenen Kontext. Über #global.context("section") wird in diesem Fall immer nur der Kontext des „innersten“ Absatzes und damit in der Regel der Absatz aus den Globalen Inhalten angesprochen.
Über #global.page.id und #global.page.name oder #global.page.uid bzw. #global.section.id und #global.section.name können jeweils die ID und der Referenzname der Seite bzw. des Absatzes aus der Inhalte-Verwaltung bzw. aus den Globalen Inhalten ausgegeben werden.

Variablen, die in den Seiten- und Absatzvorlagen definiert werden, auf denen die Seiten (PS) und (GCA) bzw. Absätze (PS) und (GCA) basieren, gelten standardmäßig für die aktuelle Seite bzw. den aktuellen Absatz sowie für alle inneren Elemente. Soll eine Variable auch in den äußeren Elementen verfügbar gemacht werden, kann dazu #global.context("PAGE") verwendet werden.

Werden in den Seiten- und Absatzvorlagen Variablen mit demselben Bezeichner definiert, gilt immer die Variable des aktuellen Elements. Das heißt, in jeder Vorlage kann auf die in dieser Vorlage definierten Variablen mit den bekannten Anweisungen (siehe auch Seite Variablen in Vorlagen) zugegriffen werden.

Um sicherzustellen, dass über jede der Vorlagen für die Seite und Absätze aus der Inhalte-Verwaltung sowie aus den Globalen Inhalten auf die Variablen des aktuellen Elements und der anderen Elemente zugegriffen werden kann, sollten eindeutige Variablenbezeichner in den Vorlagen gewählt werden.

Druckversion | Seitenanfang