$CMS_RENDER(...)$

Verwendung von $CMS_RENDER(...)$

Die Anweisung $CMS_RENDER(...)$ dient dazu, innerhalb einer Vorlage:

• einen anderen Ausgabekanal an der aufrufenden Stelle auszuwerten
• den Inhalt einer Formatvorlage einzubinden
• ein Skript aufzurufen

Syntax von $CMS_RENDER(...)$

Bei Verwendung von $CMS_RENDER(...)$ muss folgende Syntax eingehalten werden:

$CMS_RENDER(template:"BEZEICHNER",
  BEZEICHNER_1:WERT_1,
  BEZEICHNER_2:WERT_2,
  ...
  BEZEICHNER_N:WERT_N
)$

bzw.

$CMS_RENDER(script:"BEZEICHNER",
  BEZEICHNER_1:WERT_1,
  BEZEICHNER_2:WERT_2,
  ...
  BEZEICHNER_N:WERT_N
)$

Innerhalb einer $CMS_RENDER(...)$-Anweisung können mehrere Parameter kommasepariert übergeben werden, z. B.:

$CMS_RENDER(template:"tooltip", infoLayer:st_infoLayer)$

Alle Parameter bis auf template bzw. script sind optional.

$CMS_RENDER(#this, templateSet:"BEZEICHNER", pinTemplateSet:BOOLEAN)$

Der Parameter pinTemplateSet ist optional.

Parameter von $CMS_RENDER(...)$

$CMS_RENDER(...)$ verfügt über folgende Parameter:

• #this, template oder script
• Benutzerspezifizierte Parameter

Quelltext eines anderen Ausgabekanals einbinden

Über die Syntax #this, templateSet:"BEZEICHNER" wird der Quelltext eines anderen Ausgabekanals derselben Vorlage an der entsprechenden Stelle ausgegeben.

Über den optionalen Parameter pinTemplateSet kann definiert werden, ob der Aufruf anderer Templates in diesem Quelltext ebenfalls in dem aufgerufenen Ausgabekanal erfolgen soll (true, Standardwert) oder ob dabei wieder in den ursprünglichen Ausgabekanal zurück gewechselt werden soll (false).

$CMS_RENDER(#this, templateSet:"BEZEICHNER", pinTemplateSet:BOOLEAN)$

Inhalt einer Formatvorlage einbinden (template)

Der Parameter template definiert die Formatvorlage, die an der aktuellen Position einer Vorlage eingebunden werden soll.

$CMS_RENDER(template:"BEZEICHNER",...)$

Bei dem BEZEICHNER handelt es sich um das Kürzel der Formatvorlage, welche eingebunden werden soll.

Standardmäßig wird immer die Vorlagenversion des gerade generierten Vorlagensatzes verwendet.

Skriptaufrufe innerhalb einer Vorlage (script)

Skripte, die im Projekt als Skripttyp „Vorlage“ (siehe Bereich Scripting) angelegt wurden, können über die Anweisung $CMS_RENDER(...)$ aus einer Seiten- oder Absatzvorlage und auch aus Verweisen heraus verwendet werden:

$CMS_RENDER(script:"BEZEICHNER",...)$

Bei dem BEZEICHNER handelt es sich um den Referenznamen des Skripts, welches angesprochen werden soll.

Standardmäßig wird immer die Vorlagenversion des gerade generierten Vorlagensatzes verwendet.

Benutzerspezifizierte Parameter

Über die Anweisung kann der Formatvorlage oder dem Skript auch eine beliebige Menge von benutzerspezifizierten Parametern übergeben werden.

Der Bezeichner eines Parameters wird durch einen Doppelpunkt (:) vom Wert getrennt.

Jeder benutzerspezifizierter Parameter wird wiederum durch ein Komma (,) getrennt:

...,BEZEICHNER_1:"WERT_1",BEZEICHNER_2:OBJEKT_2, ...,BEZEICHNER_N:"WERT_N"

Als Wert kann entweder ein Objekt bzw. eine Variable oder ein textueller Wert (wird in doppelten Hochkommata eingefasst) übergeben werden.

Der Wert steht dann in der Formatvorlage bzw. im Skript unter dem BEZEICHNER zur Verfügung, z. B.

$-- Seitenvorlage: --$
$CMS_RENDER(template:"Ausgabe",variable:"WERT")$

$-- Formatvorlage "Ausgabe": --$
Ausgabe: $CMS_VALUE(variable)$

oder

$-- Seitenvorlage: --$
$CMS_RENDER(script:"SkriptAusgabe",variable:"WERT")$

$-- Skript "SkriptAusgabe": --$
//!BeanShell
result.setValue(gc.getVariableValue("variable"));

Für benutzerspezifizierte Parameter sollten nicht die Bezeichner template, script oder version verwendet werden!

Beispiele zu $CMS_RENDER(...)$

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 an die spezifischen Variablennamen des Projekts angepasst werden, in dem die Anweisung verwendet werden soll.

1. Beispiel: Konditionale Ausgabe mithilfe einer Formatvorlage

Codebeispiel:

$-- Seitenvorlage: --$
$CMS_RENDER(template:"DefaultLayoutTemplate",style:true,value:"Wert")$

$-- Formatvorlage "DefaultLayoutTemplate": --$
$CMS_IF(style)$
    <b>$CMS_VALUE(value)$</b>
$CMS_ELSE$
   <i>$CMS_VALUE(value)$</i>
$CMS_END_IF$

Beschreibung:

Abhängig vom Wert des Übergabeparameters style wird der bei value angegebene Wert formatiert ausgegeben. Ist der Wert von style auf true gesetzt, wird der Wert in fetter Schrift ausgegeben, ist der Wert auf false gesetzt, wird der Wert kursiv ausgegeben.

Ausgabe:

<b>Wert</b>

2. Beispiel: Ausgabe in Verbindung mit einem Skript

Codebeispiel:

$-- Seitenvorlage: --$
$CMS_RENDER(script:"SkriptAusgabe",value:"Wert")$

$-- Skript "SkriptAusgabe": --$
//!BeanShell
result.setValue(gc.getVariableValue("value"));

Beschreibung:

Das Skript SkriptAusgabe gibt den Wert des Übergabeparameters value aus.

Ausgabe:

Wert 

3. Beispiel: Arbeiten mit Vorlagenfragmenten (und unterschiedlichen Kontexten)

Innerhalb einer Vorlage können über $CMS_SET(...)$-Blöcke und $CMS_RENDER(...)$-Aufrufe Vorlagenfragmente inkludiert und als eine Art „lokale Funktion“ eingesetzt werden:

$CMS_SET(_local_template)$
     [Inhalte]
$CMS_END_SET$ 
$CMS_RENDER(template: _local_template, _variant_class: "variant-1")$ 
[Inhalte] 
$CMS_RENDER(template: _local_template, _variant_class: "variant-2")$

Wie das im Einzelnen funktioniert, zeigt das folgende Codebeispiel:

$CMS_SET(param, "Value A")$ <!--set initial value -->
$CMS_SET(set_param1)$ 
  [Inside CMS_SET_BLOCK] $CMS_VALUE(param)$
   $--Try to overwrite outer param from inside CMS_RENDER call --$
   $CMS_SET(param, "Value C")$ 
$CMS_END_SET$

[A] $CMS_VALUE(param)$<br> 
[B] $CMS_RENDER(set_param1, param:"Value B")$ => is not overwritten by CMS_SET of param!<br>
[C] $CMS_VALUE(param)$<br>
[D] $CMS_VALUE(set_param1)$<br>
[E] $CMS_VALUE(param)$ => now param has a different value as CMS_VALUE does not create a separate scope here!<br>

Beschreibung:

Das Beispiel verdeutlicht den Umgang mit Variablen in unterschiedlichen Kontexten innerhalb einer Vorlage (zu Informationen zu Kontexten siehe auch Kapitel Variablen und Kontexte in FirstSpirit). Mithilfe eines $CMS_SET(...)$-Blocks können Vorlagenfragmente definiert werden, die anschließend innerhalb der Vorlage immer wieder ausgeführt werden können. Der Aufruf bleibt gleich, die Werte werden bei jedem Aufruf neu ermittelt (im Gegensatz zur Objektzuweisung über $CMS_SET(...)$).

Über die Anweisung $CMS_SET(param, "Value A")$ wird innerhalb der Vorlage die Variable param definiert und der Variablen der initiale Wert „Value A“ zugewiesen (Objektzuweisung).

Über $CMS_SET(set_param1)$ [Inside CMS_SET_BLOCK] $CMS_VALUE(param)$$CMS_END_SET$ wird ein Vorlagenfragment innerhalb der bestehenden Vorlage erzeugt. Der im Rumpf des Vorlagenfragments enthaltene Code – hier $CMS_VALUE(param)$ – wird bei einer Auswertung der CMS_SET-Variable (durch $CMS_VALUE(set_param1)$ oder durch $CMS_RENDER(set_param1, ...)$) durchlaufen. Allerdings mit einem entscheidenen Unterschied:
Der $CMS_RENDER(...)$-Aufruf erzeugt einen eigenen Kontext (im Unterschied zum Aufruf per $CMS_VALUE(...)$) (siehe unten).

Die Ausgabe für das Beispiel lautet:

[A] Value A
[B] [Inside CMS_SET_BLOCK] Value B => is not overwritten by CMS_SET of param!
[C] Value A
[D] [Inside CMS_SET_BLOCK] Value A 
[E] Value C => now param has a different value as CMS_VALUE does not create a separate scope here!

[A]: Ausgabe des initial gesetzten Werts für den Parameter (Value A).

[B]: Über den Aufruf $CMS_RENDER(set_param1, param:"Value B")$ wird der Parmeter param mit dem Wert Value B übergeben. Dabei erzeugt der $CMS_RENDER(...)$-Aufruf einen eigenen Kontext (im Unterschied zum Aufruf per $CMS_VALUE(...)$). Innerhalb des $CMS_SET(...)$-Blocks können (wenn der Aufruf über $CMS_RENDER(...)$ erfolgt) somit keine Variablen des äußeren Kontextes überschrieben werden. Der Ausdruck $CMS_SET(param, "Value C")$ wirkt sich also beim Aufruf über $CMS_RENDER(...)$ nicht aus.

[C] und [D]: die Ausgabe über $CMS_VALUE(...)$ zeigt, dass die Werte der Variablen sich nicht geändert haben (im äußeren Kontext). Beim Aufruf von $CMS_VALUE(set_param1)$ wird der $CMS_SET(...)$-Blocks erneut ausgeführt (diesmal aber im äußeren Kontext).

[E]: Damit ändert sich der Parameter (im äußeren Kontext) über den Ausdruck $CMS_SET(param, "Value C")$ diesmal tatsächlich.

4. Beispiel: Seitenvorlage, in der der Inhalt der Absätze ausgewertet und aufbereitet ist.

Dies soll über mehrere Ausgabekanäle hinweg identisch erfolgen.

Codebeispiel:

...
$CMS_RENDER(#this, templateSet:"logicChannel")$
$CMS_FOR(for_entry, set_valuelist)$
...
$CMS_END_FOR$
...

In dem technischen Ausgabekanal logicChannel werden dann die Absätze aufgerufen und die benötigten Informationen in einer Liste im Kontext der Seitenvorlage gespeichert:

$CMS_SET(set_valuelist, [])$
$CMS_VALUE(#global.page.body("myBody"))$

In den einzelnen Absätzen werden dann die Informationen ausgelesen und in die Liste hinzugefügt (wobei set_resultvar das Ergebnis der Auswertung ist):

...
$CMS_SET(set_valuelist[set_valuelist.size], set_resultvar)$

5. Beispiel: In einem Absatz soll eine contentSelect Funktion in verschiedenen Ausgabekanälen benutzt werden.

Um diese leichter pflegbar zu machen, wird diese contentSelect Funktion aber nur einmal in einem technischen Ausgabekanal verwendet:

...
$CMS_RENDER(#this, templateSet:"logicChannel")$
$CMS_FOR(for_entity, fr_myContentSelect.map(entity->entity.getDataset("<UID Tabletemplate>")))$
...
$CMS_END_FOR$
...

Im logicChannel würde dann folgendes zu finden sein:

<CMS_HEADER>
 <CMS_FUNCTION name="contentSelect" resultname="fr_myContentSelect">
 ...
 </CMS_FUNCTION>
</CMS_HEADER>

Sofern die Ausgabe der Datensätze nicht spezifisch für die einzelnen Ausgabekanäle ist, ist es auch sinnvoll, diese direkt im logicChannel Ausgabekanal auszugeben, damit der entsprechende Code auch nur einmal gepflegt werden muss.