$CMS_SET(...)$

Verwendung von $CMS_SET(...)$

Über die Anweisung $CMS_SET(...)$ kann innerhalb einer Vorlage eine Variable definiert und der Variable ein Wert zugewiesen werden.

Syntax von $CMS_SET(...)$

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

$CMS_SET(BEZEICHNER,OBJEKT)$

bzw.

$CMS_SET(BEZEICHNER)$
  RUMPF DES VORLAGENFRAGMENTES
$CMS_END_SET$

Innerhalb einer $CMS_SET(...)$-Anweisung können mehrere Variablen bzw. Variablen und Zuweisungen kommasepariert übergeben werden, z.B.:

$CMS_SET(var1, var2)$ 

In BEZEICHNER und in OBJEKT darf kein $CMS_VALUE(...)$, wie z.B. $CMS_SET(varname$CMS_VALUE(a)$,"b")$ oder $CMS_SET(a,"b$CMS_VALUE(c)$")$, verwendet werden. Solche Ausdrücke können nur zwischen $CMS_SET(BEZEICHNER)$ und $CMS_END_SET$ verwendet werden (oben als RUMPF DES VORLAGENFRAGMENTES gekennzeichnet) .

Bei dem ersten Ausdruck handelt es sich um eine Objektzuweisung, z.B. String, Zahl usw.. Der zweite Ausdruck beschreibt die Erzeugung eines Vorlagenfragmentes, welches z.B. mit einer Absatzvorlage vergleichbar ist.

Parameter von $CMS_SET(...)$

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

• BEZEICHNER
• OBJEKT oder RUMPF

BEZEICHNER

Unter dem angegebenen Bezeichner ist das zugewiesene Objekt oder das Vorlagenfragment im Quelltext der Vorlage aufrufbar:

$-- Definition: --$
$CMS_SET(varName,"A")$

$-- Ausgabe: --$
$CMS_VALUE(varName)$

Der Bezeichner darf nur folgende Zeichen enthalten: A-Z, a-z, 0-9 und _.

OBJEKT

Ein Möglichkeit eine $CMS_SET(...)$-Anweisung zu definieren, ist ein Objekt zuzuweisen:

$CMS_SET(varName,"Wert")$

oder

$CMS_SET(varName1,varName2)$

oder

$CMS_SET(varName1,varName2.toString)$

Das Objekt kann sowohl eine Konstante als auch eine andere Variable oder aber ein Ausdruck sein.

Für die Weiterverarbeitung des Objekts muss der Wert des Objekts und nicht das Objekt selber zugewiesen werden. In den meisten Fällen genügt der Aufruf der Methode .toString, die eine sofortige Auflösung des Ausdruckes (siehe drittes Code-Beispiel) bewirkt.

RUMPF

Innerhalb des Rumpfes einer $CMS_SET(...)$-Anweisung können beliebige $CMS_...(...)$-Ausdrücke, wie z.B. $CMS_IF(...)$,$CMS_REF(...)$, $CMS_SET(...)$ und $CMS_VALUE(...)$, angegeben werden:

$CMS_SET(varName)$
  $CMS_IF(#global.preview)$
    Ausgabe in einer Vorschauseite
  $CMS_ELSE$
    Sonstige Ausgabe
  $CMS_END_IF$
$CMS_END_SET$

Die Verwendung des Bezeichners einer $CMS_SET(...)$-Anweisung in einer $CMS_VALUE(...)$-Anweisung im Rumpf der $CMS_SET(...)$-Anweisung kann zu einer Endlosschleife führen, da der Rumpf beim ersten Aufruf mit $CMS_VALUE(...)$ ausgewertet wird! Eine Endlosschleife kann, z.B. durch eine erzwungene Auswertung (durch .toString), oder durch vollständige Vermeidung der Bezeichner-Wiederholung vermieden werden.

Beispiel für eine Endlosschleife:

$CMS_SET(endlosschleife)$
  PREFIX$CMS_VALUE(endlosschleife)$POSTFIX
$CMS_END_SET$

$CMS_VALUE(endlosschleife)$

Im Beispiel wird versucht dem Wert von endlosschleife das Wort PREFIX voranzustellen und das Wort POSTFIX anzufügen.

In den Fehlern der Vorschau findet sich folgende Ausgabe:

ERROR: endless loop in template?

Um die Endlosschleife im Beispiel zu vermeiden, muss der Ausdruck folgendermaßen formuliert werden:

$CMS_SET(endlosschleife, "PREFIX" + endlosschleife.toString + "POSTFIX")$
$CMS_VALUE(endlosschleife)$

Durch die Neuformulierung des Ausdruckes als Zusammenfassung mehrerer Objekte (erkennbar am +) wird der Ausdruck nur einmal ausgewertet.

Auswertung

Die über die Anweisung $CMS_SET(...)$ definierte Variable kann vom Typ TemplateDocumentImpl sein. Dies bedeutet, dass der darin enthaltene Ausdruck noch nicht ausgewertet ist.

Dazu ein Beispiel (Vorlage):

$CMS_SET(myVar)$
6 * 7 = $CMS_VALUE(6 * 7)$ 
$CMS_END_SET$

Der Ausdruck $CMS_SET(...)$...$CMS_END_SET$ definiert im einen Vorlagenfragment eine Variable vom Typ TemplateDocumentImpl ( $CMS_SET(..., ...)$ hingegen nimmt eine Objektzuweisung vor). Das heißt, die Variable "myVar" ist in diesem Fall vom Typ TemplateDocumentImpl.

Um mit dem ausgewerteten Ausdruck weiterzuarbeiten, kann folgender Ausdruck verwendet werden:

$CMS_RENDER(script:"myscript", scriptVar:myVar)$

$CMS_VALUE(myVar)$ wertet den Ausdruck natürlich auch aus!

Erzeugung eines Dictionarys

Ein Dictionary kann wie folgt erzeugt werden:

$CMS_SET(BEZEICHNER, { })$

Anschließend kann eine Zuweisung mit der Methode .add erfolgen:

$CMS_SET(myDictionary, { })$
$CMS_SET(void, myDictionary.add("1. Eintrag"))$
$CMS_SET(void, myDictionary.add("2. Eintrag"))$
$CMS_SET(void, myDictionary.add("3. Eintrag"))$

Damit keine Ausgabe erfolgt bietet sich eine $CMS_SET(..)$-Anweisung mit einer Dummy-Variable (z.B. void) an:

Die Ausgabe des Dictionarys kann mit Hilfer einer $CMS_FOR(...)$-Anweisung realisiert werden:

$CMS_FOR(_wrapper, myDictionary)$
  $CMS_VALUE(_wrapper)$
$CMS_END_FOR$

Erzeugung einer Liste

Mit einer $CMS_SET(...)$-Anweisung kann eine neue Liste erzeugt werden.

Die Syntax hierfür lautet:

$CMS_SET(BEZEICHNER, [])$

Neue Einträge in einer Liste lassen sich entweder über die Angabe des Index

$CMS_SET(myList, [])$
$CMS_SET(myList[0], "1. Eintrag")$

oder durch die Methode .add realisieren:

$CMS_SET(myList, [])$
$CMS_SET(void, myList.add("1.Eintrag"))$

Die Ausgabe kann z.B. durch eine $CMS_FOR(...)$-Anweisung realisiert werden:

$CMS_FOR(_wrapper, myList)$
  $CMS_VALUE(_wrapper)$
$CMS_END_FOR$

Setzten von sprachabhängigen Werten

Über die Anweisung $CMS_SET(...)$ können sprachabhängige Variablen gesetzt werden. Sprachabhängig bedeutet, dass abhängig von der selektierten Sprache, ein anderer Variablenwert gesetzt wird.

Die Syntax für die implizite Sprachverwendung sieht folgendermaßen aus (über ein Dictionary):

$CMS_SET(langValues,{ 
  "DE" : {
    "value1" : "D-Wert1", 
    "value2" : "D-Wert2"
    },
  "EN" : {
    "value1" : "E-Wert1", 
    "value2" : "E-Wert2"
     }
})$

In diesem Fall wird über folgenden Ausdruck ein sprachabhängiger Wert ausgegeben (beim Zugriff auf ein Dictionary):

$CMS_VALUE(langValues[#global.language.abbreviation]["value1"])$

Beispiele zu $CMS_SET(...)$

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: Ersetzung einer if-Funktion durch die Anweisung $CMS_SET(...)$

Die Anweisung $CMS_SET(...)$ kann folgende Funktion <CMS_FUNCTION name="if"...> ersetzen:

<CMS_FUNCTION name="if" resultname="fr_pt_lang">
  <CMS_VALUE_PARAM name="conditionVar" value="global.language"/>
  <CMS_PARAM name="compareValue" value="EN"/>
   <CMS_CDATA_PARAM name="trueValue"><![CDATA[EN]]></CMS_CDATA_PARAM>
   <CMS_CDATA_PARAM name="falseValue"><![CDATA[nicht EN]]></CMS_CDATA_PARAM>
</CMS_FUNCTION>

Die folgende Anweisung erfüllt die Aufgaben der oben angegebenen Funktion:

$CMS_SET(fr_pt_lang)$
   $CMS_IF(#global.language.abbreviation == "EN")$
       EN
     $CMS_ELSE$
       nicht EN
   $CMS_END_IF$ 
$CMS_END_SET$

Beschreibung:

Wenn die aktuell gerenderte Sprache die Abkürzung EN enthält, so wird EN ausgegeben, andernfalls nicht EN.

Ausgabe:

$-- Bei EN --$
EN

$-- Bei nicht EN --$
nicht EN