Funktionen
Inhaltsverzeichnis |
Über den Einsatz von Funktionen kann eine gewisse Dynamik in die Ausgabe (z. B. HTML-Seiten) gebracht werden. Funktionen ermöglichen z. B. eine flexible, an bestimmte Bedingungen geknüpfte Ausgabe von einmalig durch den Redakteur eingegebenen Inhalte auf der Website und bieten funktionale Erweiterungen von Vorlagen.
Header-Funktionen
Funktionen können innerhalb von <CMS_HEADER>-Tags definiert („Header-Funktion“) werden oder innerhalb von Anweisungen. Innerhalb der <CMS_HEADER>-Tags ist nur die Eingabe von gültigem XML zulässig. Alternativ können auch Funktionen durch ein BeanShell-Skript erzeugt und eingefügt werden.
Ein <CMS_HEADER>-Tag kann in jeder Vorlagenart, für die im Vorlagensatz (siehe beispielsweise für Seitenvorlagen) eine Funktion definiert werden soll, verwendet werden. Header-Funktionen werden nur einmal, bei der Generierung einer Seite ausgeführt. Dabei können nur dem Server bekannte Funktionen in der Vorlagen-Verwaltung genutzt werden. Diese werden auf den nachfolgenden Seiten erläutert.
Header-Funktionen in FirstSpirit können folgende Aufgaben übernehmen:
- Definition von Variablen, Berechnen und Auswerten von Ausdrücken (Funktion define).
- Eingaben des Redakteurs prüfen und auswerten (Funktion define).
- Texte auf ein bereits vorhandenes Hintergrundbild rendern (Funktion Font).
- Tabellen mit komplexem Layout ausgeben (Funktion Table).
- Daten (gefiltert und / oder sortiert) aus der Datenquellen-Verwaltung ausgeben (Funktion contentSelect).
- Strukturen der Struktur-Verwaltung für die Navigation auswerten (siehe Funktion Navigation).
Das ist insbesondere auch für Menügruppen (Funktion MenuGroup)
oder Seitengruppen (Funktion PageGroup) möglich.
Syntax von Header-Funktionen
Der Grundaufbau von Header-Funktionen sieht wie folgt aus:
<CMS_FUNCTION name="FUNKTIONSBEZEICHNER" resultname="BEZEICHNER">
<CMS_PARAM name="PARAMETERNAME" value="KONSTANTE" />
<CMS_VALUE_PARAM name="PARAMETERNAME" value="AUSDRUCK" />
<CMS_CDATA_PARAM name="PARAMETERNAME">
<![CDATA[
...
]]>
</CMS_CDATA_PARAM>
</CMS_FUNCTION>
Jede CMS-Funktion wird durch ein <CMS_FUNCTION>-Tag umschlossen. In diesem müssen die Attribute name und resultname gesetzt werden:
- 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.
Übergabe von Parametern
Werte können einer Header-Funktion grundsätzlich folgendermaßen übergeben werden:
Beispiel define-Funktion:
1) <CMS_PARAM>
Bei Verwendung von
<CMS_PARAM name="source" value="konstante" />
wird der Rückgabewert der define-Funktion auf den String konstante festgelegt.
2) <CMS_VALUE_PARAM>
Bei Verwendung von
<CMS_VALUE_PARAM name="source" value="konstante" />
wird der Rückgabewert der define-Funktion auf den Ausdruck konstante festgelegt.
3) <CMS_CDATA_PARAM>
Über <CMS_CDATA_PARAM> (bzw. <CMS_ARRAY_PARAM> für die Navigation-Funktion und <CMS_NODE_PARAM> für die Table-Funktion) können Vorlagenfragmente übergeben werden, z. B.
<CMS_CDATA_PARAM name="delimiter">
<![CDATA[WERT]]>
</CMS_CDATA_PARAM>
Enthält ein Wert Anführungszeichen, gibt es folgende Möglichkeiten, um valides XML zu erzeugen:
Einfassen in einfache Anführungszeichen:
<CMS_PARAM name="source" value='Eine "Konstante" mit Anführungszeichen' />
Maskierung durch HTML-Entities:
<CMS_PARAM name="source" value="Eine "Konstante" mit Anführungszeichen" />
Parameterübergabe mittels "define"-Funktion
Es können mehrere, auch unterschiedliche Funktionen im Header verwendet werden. Die define-Funktion kann dazu verwendet werden, Variablen oder Ausdrücke zu definieren, die dann von einer anderen Header-Funktion derselben Vorlage verwendet werden kann.
Der Rückgriff auf den Wert einer „define“-Funktion erfolgt in einer anderen Funktion des Headers über <CMS_VALUE_PARAM>.
Auf diese Weise können Header-Funktionen mit Eingaben des Redakteurs (z. B. in Eingabekomponenten), Struktur-Variablen oder Projekteinstellungen verknüpft werden.
Beispiel:
Über folgende „define“-Funktion wird der Wert einer Eingabekomponente mit dem Bezeichner st_text (z. B. CMS_INPUT_TEXT) in der Variable ft_text gespeichert:
<CMS_FUNCTION name="define" resultname="ft_text">
<CMS_VALUE_PARAM name="source" value="st_text" />
</CMS_FUNCTION>
Wird in demselben Header-Bereich folgende Font-Funktion definiert
<CMS_FUNCTION name="Font" resultname="font">
<CMS_PARAM name="width" value="240" />
<CMS_PARAM name="size" value="30" />
<CMS_PARAM name="font" value="Courier" />
<CMS_PARAM name="media" value="pic" />
<CMS_PARAM name="color" value="#000000" />
<CMS_PARAM name="boxjustify" value="center" />
<CMS_PARAM name="boxvalign" value="center" />
<CMS_PARAM name="justify" value="left" />
<CMS_VALUE_PARAM name="text" value="ft_text" />
</CMS_FUNCTION>
und diese außerhalb des Header-Bereich per
<img src="$CMS_REF(font)$" />
ausgegeben, wird der Text, den der Redakteur in die Eingabekomponente mit dem Bezeichner st_text eingibt, für die Font-Funktion verwendet und der Text somit auf dem Bild mit dem Bezeichner pic ausgegeben.
Aufruf / Ausgabe von Funktionen
Funktionen können überall da aufgerufen werden, wo auch Methoden-Aufrufe verwendet werden können. Im Unterschied zu Methoden beziehen sich Funktionen aber auf kein Objekt:
Jede Funktion hat einen Funktionsbezeichner, über den sie aufgerufen werden kann. Abhängig von der Art der Funktion können ein oder mehrere Parameter übergeben werden. Neben den übergebenen Parametern besitzen Funktionen lokale Variablen, die nur innerhalb der Funktion gültig sind. Einige Funktionen liefern das Ergebnis der Ausführung als Rückgabewert zurück.
Syntax:
$CMS_VALUE(methodenName([Argumente]))$
Leerprüfung
Bei Funktionen bezieht sich eine Prüfung per isEmpty nicht darauf, ob das ausgewertete Funktionsergebnis leer ist, sondern auf das Funktions-Objekt. Daher liefert .isEmpty immer false, z. B.
$CMS_VALUE(fr_pt_mainNavi.isEmpty)$
Um beispielsweise prüfen zu können, ob das Ergebnis einer Navigationsfunktion leer ist, kann hingegen folgende Syntax verwendet werden:
$CMS_VALUE(fr_pt_mainNavi.toString.isEmpty)$
Allerdings kann dieser Aufruf je nach Projektumfang rechenzeitintensiv sein.