include

Mit der Funktion include ist es möglich, dynamische und statische Fragmente innerhalb der <CMS_HEADER>-Tags einzufügen. So können Fragmente aus dem <CMS_HEADER>-Bereich an zentraler Stelle gepflegt und verwaltet werden.

Zum Einbinden eines statischen Fragments wird ein uninterpretiertes Skript und für ein dynamisches Fragment ein Vorlagenskript benötigt.

Die Verwendung der Funktion include wird nicht empfohlen. Diese Funktion wird in einer späteren Version entfallen. Bitte verwenden Sie anstelle der include-Funktion $CMS_RENDER(..)$-Anweisungen.

Statisches Einfügen einer define-Funktion mit $CMS_RENDER(...)$-Anweisung

Statt ein uninterpretiertes Skript mithilfe der Funktion include einzufügen, wird die Realisierung mit einer $CMS_RENDER(..)$-Anweisung in Verbindung mit einer Formatvorlage empfohlen.

Die Kombination aus dem uninterpretierten Skript uninterpreted:

<CMS_FUNCTION name="define" resultname="uninterpretedScript">
  <CMS_CDATA_PARAM name="source"><![CDATA[Ausgabe eines uninterpretierten Skriptes]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

und seiner Verwendung in einer define-Funktion in einer Seitenvorlage:

<CMS_HEADER>
  <CMS_FUNCTION name="include" resultname="void">
    <CMS_PARAM name="name"  value="uninterpreted" />
  </CMS_FUNCTION>
</CMS_HEADER>$CMS_VALUE(uninterpretedScript)$

lässt sich wie folgt umschreiben:

Der Inhalt des uninterpretierten Skripts wird in eine Formatvorlage mit dem Bezeichner templateFragment kopiert.
Vor dem öffnenden <CMS_FUNCTION>-Tag wird ein öffnendes <CMS_HEADER>-Tag eingefügt.
Nach dem schließenden <CMS_FUNCTION>-Tag wird ein schließendes <CMS_HEADER>-Tag eingefügt.

Da die Auswertung einer Formatvorlage in einem eigenen Kontext erfolgt, kann ohne Anpassung der Funktion nicht auf diese zugegriffen werden. Um die Funktion auch in einem anderen Kontext (in diesem Fall im Kontext der aufrufenden Vorlage, z. B. Seitenvorlage, Absatzvorlage usw.) benutzen zu können, gibt es das Attribut context. Der Wert für das Attribut ist der Kontextbezeichner, in dem die Funktion zur Verfügung gestellt werden soll, z. B. section für die Absatzvorlage und PAGE für die Seitenvorlage.

Das Attribut context sollte nur für diesen Sonderfall genutzt werden, da über das Attribut gleichlautende Variablen in anderen Kontexten überschrieben werden und sich damit die Verfügbarkeit ändern kann. Bsp.: Absatz 1: Variable A ist nur in Absatz 1 gültig. Setzt man die Variable in den Seitenkontext, ist die Variable A mit dem Wert aus Absatz 1 auch in Absatz 2 gültig. Siehe dazu auch das Kapitel Kontexte.

Nach der $CMS_RENDER(..)$-Anweisung steht die Funktion dann im angegebenen Kontext zur Verfügung.

Um die define-Funktion aus dem Beispiel in der Seitenfunktion verfügbar zu machen, ist im <CMS_FUNCTION>-Tag das Attribut context mit dem Wert PAGE hinzuzufügen.

Der Inhalt der Formatvorlage sieht dann in etwa so aus:

<CMS_HEADER>
  <CMS_FUNCTION name="define" resultname="uninterpretedScript" context="PAGE">
    <CMS_CDATA_PARAM name="source"><![CDATA[Ausgabe eines uninterpretierten Skriptes]]></CMS_CDATA_PARAM>
  </CMS_FUNCTION>
</CMS_HEADER>

Die Verwendung der Formatvorlage in der Seitenvorlage lautet:

$CMS_RENDER(template:"templateFragment")$$CMS_VALUE(uninterpretedScript)$

Variablen, die innerhalb des Fragmentes zur Verfügung stehen sollen, müssen vor der $CMS_RENDER(...)$-Anweisung definiert werden!

Dynamisches Einfügen einer define-Funktion mit $CMS_RENDER(...)$-Anweisung

Statt ein Skript mithilfe der Funktion include einzufügen, wird die Realisierung mithilfe einer $CMS_RENDER(..)$-Anweisung empfohlen.

Die Kombination eines Skripts interpreted:

//!BeanShell
out = new StringBuilder();
out.append("<CMS_FUNCTION name=\"define\" resultname=\"interpretedScript\">");
out.append("<CMS_CDATA_PARAM name=\"source\"><![CDATA[Ausgabe eines interpretierten Skriptes<br>");
out.append("Der Wert des Übergabeparameters ist:").append(output).append("]]></CMS_CDATA_PARAM>");
out.append("</CMS_FUNCTION>");
result.setValue(out.toString());

und seiner Verwendung in einer define-Funktion in einer Seitenvorlage:

<CMS_HEADER>
  <CMS_FUNCTION name="include" resultname="void">
    <CMS_PARAM name="name"  value="interpreted" />
    <CMS_PARAM name="output" value="AUSGABEWERT" />
  </CMS_FUNCTION>
</CMS_HEADER>$CMS_VALUE(interpretedScript)$

lässt sich wie folgt umschreiben:

Das Skript ist so zu ändern, dass ein Vorlagenfragment in den Kontext geschrieben wird. Dafür ist ein öffnendes und schließendes <CMS_FUNCTION>-Tag einzufügen. Aus dem Fragment muss mit ParserUtil.parseTemplate(...) eine Vorlage erzeugt und das Ergebnis mit context.print(...) in den Kontext geschrieben werden.
Zusätzlich ist zu beachten, dass Variablen nicht automatisch zur Verfügung stehen (im obigen Beispiel output), sondern mit context.getVariableValue(...) aus dem Kontext bezogen werden müssen. Das obige Beispiel sieht nach den Änderungen wie folgt aus:

//!BeanShell
import de.espirit.firstspirit.generate.ParserUtil;

out = new StringBuilder();
out.append("<CMS_HEADER>");
out.append("<CMS_FUNCTION name=\"define\" resultname=\"interpretedScript\">");
out.append("<CMS_CDATA_PARAM name=\"source\"><![CDATA[Ausgabe eines interpretierten Skriptes<br>");
out.append("Der Wert des Übergabeparameters ist:").append(context.getVariableValue("output")).append("]]></CMS_CDATA_PARAM>");
out.append("</CMS_FUNCTION>");
out.append("</CMS_HEADER>");
context.print(ParserUtil.parseTemplate(out.toString()));

Der Aufruf im Kontext erfolgt dann folgendermaßen:

$CMS_SET(output, "AUSGABEWERT")$
$CMS_RENDER(script:"interpreted")$
$CMS_VALUE(eval(interpretedScript))$

Syntax der include-Funktion

Der Grundaufbau der Funktion include sieht wie folgt aus:

<CMS_FUNCTION name="include" resultname="void">
  <CMS_PARAM name="name" value="BEZEICHNER" />
  <CMS_PARAM name="version" value="BEZEICHNER" />
  <CMS_VALUE_PARAM name="BEZEICHNER" value="WERT" />
  <CMS_PARAM name="BEZEICHNER" value="WERT" />
</CMS_FUNCTION>

Bei dem Parameter name handelt es sich um einen Pflichtparameter. Alle anderen Parameter sind optional.

Parameter name

Mit dem Pflichtparameter name gibt man den eindeutigen Bezeichner des einzufügenden Skripts an.

Parameter version

Mit dem optionalen Parameter version kann der eindeutige Bezeichner eines Präsentationskanals angegeben werden.

Dies ist sinnvoll, um Redundanzen zu vermeiden, beispielsweise wenn ein BeanShell-Skript ausschließlich in einem Präsentationskanal gepflegt wird.

Wird der Parameter nicht angegeben, so wird versucht den aktuellen Präsentationskanal des Skripts einzufügen.

Benutzerspezifische Parameter

Zusätzlich können benutzerspezifische Parameter angegeben werden, um den Skripten weitere Informationen zur Verfügung zu stellen.

Der Parameter kann sowohl als Konstante:

<CMS_FUNCTION name="include" resultname="name">
  ...
  <CMS_PARAM name="source" value="Eine Konstante" />
</CMS_FUNCTION>

als auch als Ausdruck definiert werden:

<CMS_FUNCTION name="include" resultname="name">
  ...
  <CMS_VALUE_PARAM name="source" value="4 * 2 - 5" />
</CMS_FUNCTION>

Der Wert des Parameters (Attribut value) steht in einem Vorlagenskript, unter dem für das Attribute name vergebenen Bezeichner, zur Verfügung:

...
print(BEZEICHNER);
...

Beispiele zur Funktion include

Nachfolgend werden einige Beispiele zur Verwendung der Anweisung innerhalb von Vorlagen gezeigt. Die Beispiele sollen die konkrete Auswirkung der Anweisung verdeutlichen und eine Hilfe für den Vorlagenentwickler bei der Erstellung eigener Vorlagen sein.

Für die Verwendung innerhalb eines Projekts müssen die hier gezeigten Beispiele angepasst werden! Beispielsweise müssen Variablennamen auf die spezifischen Variablennamen des Projekts geändert werden, in dem die Anweisung verwendet werden soll.

1. Beispiel: Statisches Einfügen eines uninterpretierten Skripts

Das Einfügen eines uninterpretierten Skripts mithilfe der Funktion include lässt sich wie folgt realisieren.

Der Inhalt des uninterpretierten Skripts uninterpreted lautet:

<CMS_FUNCTION name="define" resultname="uninterpretedScript">
  <CMS_CDATA_PARAM name="source"><![CDATA[Ausgabe eines uninterpretierten Skriptes]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

Das Einfügen des Skripts erfolgt dann mit der define-Funktion in einer Seitenvorlage:

<CMS_FUNCTION name="include" resultname="void">
  <CMS_PARAM name="name"  value="uninterpreted" />
</CMS_FUNCTION>

Der Aufruf der Funktion erfolgt dann mittels:

$CMS_VALUE(uninterpretedScript)$

Die Ausgabe lautet:

Ausgabe eines uninterpretierten Skriptes

Dynamisches Einfügen einer define-Funktion mit $CMS_RENDER(...)$-Anweisung

Ausgehend vom Inhalt des Vorlagen-Skripts interpreted:

//!BeanShell
out = new StringBuilder();
out.append("<CMS_FUNCTION name=\"define\" resultname=\"interpretedScript\">");
out.append("<CMS_CDATA_PARAM name=\"source\"><![CDATA[Ausgabe eines interpretierten Skriptes<br>");
out.append("Der Wert des Übergabeparameters ist:").append(output).append("]]></CMS_CDATA_PARAM>");
out.append("</CMS_FUNCTION>");
result.setValue(out.toString());

wird das Skript mit der define-Funktion in einer Seitenvorlage eingefügt:

<CMS_FUNCTION name="include" resultname="void">
  <CMS_PARAM name="name"  value="interpreted" />
  <CMS_PARAM name="output" value="AUSGABEWERT" />
</CMS_FUNCTION>

Der Aufruf der Funktion lautet:

$CMS_VALUE(interpretedScript)$

Die Ausgabe lautet dann:

Ausgabe eines interpretierten Skriptes<br>
AUSGABEWERT