Variablen in Vorlagen

Definitionsmöglichkeiten für Variablen in Vorlagen

Häufig werden Variablen in Vorlagen (Seiten-, Absatz-, Verweis-, Format-, Tabellen-Vorlagen, Skripte) definiert.

Hier ist eine Definition an folgenden Stellen möglich:

• Definition von Variablen im Formular-Bereich
• Definition von Variablen im Präsentationskanal
  • im Header-Bereich (<CMS_HEADER>)
  • im Body-Bereich

Wertezuweisung

Grundsätzlich unterscheiden sich Variablen, die über Vorlagen definiert werden, hinsichtlich der Wertezuweisung:

1. Variablen, die auf dem Formular-Register definiert sind
   können Werte nur durch den Redakteur zugewiesen werden. Allerdings stehen dem Vorlagenentwickler einige Möglichkeiten zur Verfügung, um die Wertezuweisung durch den Redakteur zu beeinflussen und bis zu einem gewissen Grad zu steuern. Siehe dazu Abschnitt Einflussnahme auf die Wertezuweisung.
2. Variablen, die auf dem Präsentationskanal-Register definiert sind
   können Werte nicht direkt durch den Redakteur zugewiesen werden. Typische Variablen sind hier daher
   • Funktionsbezeichner (z. B. <CMS_FUNCTION name="define" resultname="BEZEICHNER">)
   • Hilfsvariablen (Variablen, in denen ein Wert (zwischen)gespeichert und an einer anderen Stelle in derselben oder in einer anderen Vorlage ausgegeben wird)

Variablen im Formular-Bereich

Die meisten Vorlagentypen verfügen über ein Register Formular. Über dieses Register werden dem Redakteur Eingabemasken zur Verfügung gestellt, mit der er die Inhalte seiner Website in FirstSpirit eingeben und verwalten kann. Dazu kann der Vorlagenentwickler auf die im Kapitel Formulare beschriebenen Eingabekomponenten zurückgreifen. Jeder Eingabekomponente wird innerhalb einer Vorlage ein eindeutiger Bezeichner (Variablenname) zugewiesen. Über diesen Variablennamen kann später auf die vom Redakteur eingegebenen Inhalte zugegriffen werden.

Sind die Bezeichner innerhalb der Vorlagen nicht eindeutig, können bereits gespeicherte Inhalte in der Datenbank durch neue Inhalte überschrieben werden.

Verwendet ein Redakteur eine Vorlage, z. B. eine Seitenvorlage als Grundlage für eine neue Seite, und schreibt Inhalte in die dort definierten Eingabekomponenten, wird dieser Inhalt beim Speichern der Seite in eine Datenbank geschrieben. Über den eindeutigen Bezeichner (Variablenname) kann nun auf den Inhalt der Variable, das heißt den redaktionellen Inhalt aus der Eingabekomponente zugegriffen werden. Der Variableninhalt kann innerhalb der Ausgabekanäle ausgegeben (Ausgabe über $CMS_VALUE(...)$) oder auch manipuliert, geändert und erneut gespeichert werden (siehe Operationen).

Einflussnahme auf die Wertezuweisung

Mit der Definition einer Eingabekomponente im Formular-Register durch den Vorlagenentwickler stehen die Werte der Eingabekomponenten in den Präsentationskanälen zur Verfügung. Dabei stehen dem Vorlagenentwickler einige Möglichkeiten zur Verfügung, um die Wertezuweisung zu beeinflussen, um so z. B. dafür sorgen zu können, dass auch tatsächlich Werte zugewiesen werden, um Redakteure an bestimmte Vorgaben (z. B. Style-Guide) binden oder Fehleingaben unterbinden zu können. Einige der Möglichkeiten sind direkt in der Oberfläche des Java- und WebClients für den Redakteur zu sehen, andere verarbeiten die Eingaben des Redakteurs „im Hintergrund“.

Variablen im Präsentationskanal-Bereich

Im Gegensatz zu Variablen, die im Formular-Bereich definiert werden, hat der Redakteur bei Variablen, die im Präsentationskanal-Bereich definiert werden, keine Möglichkeit, direkt einen Wert zuzuweisen. Daher ist der Wert einer Variable, die im Präsentationskanal-Bereich definiert wird, zumeist wiederum eine Variable, entweder eine vom Vorlagenentwickler definierte oder eine Systemvariable (siehe Systemobjekte).

Auf Variablen, die im Präsentationskanal-Bereich definiert werden, kann nicht im Formular-Bereich zugegriffen werden. Der Inhalt dieser Variablen kann hingegen ebenfalls über den Präsentationskanal-Bereich ausgegeben (über $CMS_VALUE(...)$) oder manipuliert, geändert und erneut gespeichert werden (siehe Operationen).

Variablen im Header-Bereich

<CMS_FUNCTION>
Variablen können auch auf den Präsentationskanal-Registern (auch „Ausgabekanal“) definiert werden, und zwar über Funktionen.

Mithilfe von Funktionen können in FirstSpirit z. B. Datensätze aus Datenquellen dynamisch nach bestimmten Kriterien auf einer Seite auszugeben oder automatisch eine Navigation aus der Baumstruktur der Struktur-Verwaltung zu erzeugen. Sie werden durch ein <CMS_FUNCTION>-Tag umschlossen, und müssen die Attribute name und resultname enthalten. Der zu name definierte Wert ist der Funktionsbezeichner, mit dem die Funktion aufgerufen werden kann, in resultname wird der Bezeichner der Rückgabevariable definiert, die das Ergebnis der Funktion speichert. Funktionen werden nur einmal bei der Generierung einer Seite ausgeführt.

Einige der FirstSpirit-Funktionen müssen im Header-Bereich definiert werden:

• contentSelect: sortierte / gefilterte Ausgabe von Datensätzen aus der Datenquellen-Verwaltung
• define: Definition einer Variable und Zuweisen eines Wertes
• Font: Erzeugung eine Grafik aus einem Text in True-Type-Schrift (.ttf)
• MenuGroup: Gruppierte Ausgabe von Menüebenen der gleichen Ebene
• Navigation: Erzeugung einer Navigation
• PageGroup: Ausgabe von Seitengruppen
• Table: Darstellung von komplexen Tabellen

Siehe dazu auch Kapitel Funktionen.

<CMS_VALUE>
Die Definition einer Variablen ist auch über das Tag <CMS_VALUE> innerhalb eines Präsentationskanals einer Vorlage möglich. Der Tag <CMS_VALUE> kann nur im Header-Bereich der Vorlage, also innerhalb der Tags <CMS_HEADER> verwendet werden.

Dabei muss folgende Syntax eingehalten werden:

<CMS_VALUE name="...">
  <LANG id="DE">
    <ATTR name="self">...</ATTR>
  </LANG>
  <LANG id="EN">
    <ATTR name="self">...</ATTR>
  </LANG>
</CMS_VALUE>

Wie das oben angegebene Codebeispiel zeigt, werden die Inhalte der Variable sprachabhängig angegeben. Jeder Inhalt wird daher in einem eigenen <LANG>-Tag abgelegt. Abhängig von der selektierten Ausgabesprache kann dann ein anderer Inhalt ausgegeben werden. Da die sprachabhängige Ausgabe eines Variableninhalts innerhalb einer Funktion durchgeführt wird, muss die Deklaration der Variable per <CMS_VALUE>-Tag schon vor dem Parsing der Funktion bekannt sein. Das heißt, der oben angegebene Codeausschnitt muss noch vor den <CMS_FUNCTION>-Tags im <CMS_HEADER>-Bereich der Vorlage stehen.

Beispiel:

<CMS_VALUE name="Beschriftung">
  <LANG id="DE">
    <ATTR name="self">Mann</ATTR>
    <ATTR name="woman">Frau</ATTR>
    <ATTR name="child">Kind</ATTR>
    <ATTR name="teen">Jugendlicher</ATTR>
    <ATTR name="senior">Senior</ATTR>
  </LANG>
  <LANG id="EN">
    <ATTR name="self">man</ATTR>
    <ATTR name="woman">woman</ATTR>
    <ATTR name="child">child</ATTR>
    <ATTR name="teen">teen</ATTR>
    <ATTR name="senior">senior</ATTR>
  </LANG>
</CMS_VALUE>

Bei der Definition muss das Attribut self angegeben werden. Der hiermit festgelegte Wert kann im Body-Bereich der Seite kann mithilfe folgender Notation abgerufen werden.

Auf die Werte der weiteren Attribute kann über die Punktnotation zugegriffen werden:

Variablen im Body-Bereich

Über die Anweisung $CMS_SET(...)$ kann im Body-Bereich eine Variable definiert und der Variable ein Wert zugewiesen werden.

Beispiel:

$CMS_SET(myVar,"Das ist ein Text mit \"Sonderzeichen\".")$
$CMS_VALUE(myVar)$ 

Ausgabe:

Das ist ein Text mit "Sonderzeichen".

Im oben angegebenen Codebeispiel wird der Variablen myVar die Zeichenkette "Das ist ein Text mit \"Sonderzeichen\"." übergeben und ein String-Objekt erzeugt. Anfang und Ende der Zeichenkette werden durch die Anführungszeichen markiert. Da innerhalb des Strings ebenfalls das Zeichen " verwendet wird, muss zusätzlich '\' als Escape-Zeichen in die Zeichenkette eingefügt werden. Diese Zeichen tauchen in der Ausgabe jedoch nicht auf. Der Inhalt der Variablen kann über die Anweisung $CMS_VALUE(myVar)$ ausgegeben werden. Innerhalb des Ausgabekanals wird das String-Objekt "Das ist ein Text mit "Sonderzeichen"." ausgegeben.

Variableninhalte können auch folgendermaßen zugewiesen werden:

$CMS_SET(myVar2,myVar.toString.toUpperCase)$
$CMS_VALUE(myVar2)$

Ausgabe:

DAS IST EIN TEXT MIT "SONDERZEICHEN".

Im Codebeispiel wird der Wert der Variablen myVar modifiziert und in einer neuen Variablen myVar2 gespeichert.

Bei den bisherigen Beispielen wurden einfache String-Objekte erzeugt. Sollen komplexere Objekte verwendet werden, muss ein Document-Objekt erzeugt werden. Diese komplexen Objekte können auch CMS-Ausdrücke enthalten:

$CMS_SET(myVar3)$
      $CMS_VALUE(myVar2)$
$CMS_END_SET$

Um den Unterschied deutlich zu machen:

1) Beispiel "Einfaches String-Objekt":

$CMS_SET(myVar,"Das ist einfaches String-Objekt")$
$CMS_SET(myVar2,"CMS")$
myVar:$CMS_VALUE(myVar)$
Klasse:$CMS_VALUE(myVar.class)$

Ausgabe:

myVar:Das ist einfaches String-Objekt
Klasse:java.lang.String

2) Beispiel "Komplexes Document-Objekt":

$CMS_SET(myVar3)$Das ist ein komplexes Document-Objekt mit $CMS_VALUE(myVar2)$ Ausdrücken.$CMS_END_SET$
$CMS_SET(myVar3)$$CMS_VALUE(myVar2)$$CMS_END_SET$
MyVar3:$CMS_VALUE(myVar3)$
Klasse:$CMS_VALUE(myVar3.class)$

Ausgabe:

MyVar3:CMS-Ausdruck
Klasse:de.espirit.firstspirit.parser.impl.TemplateDocumentImpl

Weitere Informationen siehe Kapitel $CMS_SET(...)$.