$CMS_SET(...)$
| Inhaltsverzeichnis |
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(...)$ gibt es syntaktisch zwei Möglichkeiten.
Variante 1:
$CMS_SET(BEZEICHNER,OBJEKT)$
Variante 2:
$CMS_SET(BEZEICHNER)$
RUMPF DES VORLAGENFRAGMENTES
$CMS_END_SET$
Bei der ersten Variante handelt es sich um eine Objektzuweisung, z. B. String, Zahl usw. Die zweite Variante beschreibt die Erzeugung eines Vorlagenfragmentes, welches z. B. mit einer Absatzvorlage vergleichbar ist. Zudem wird in diesem Fall der gesamte RUMPF DES VORLAGENFRAGMENTES bei einer Auswertung der CMS_SET-Variable (etwa durch $CMS_VALUE(BEZEICHNER)$ durchlaufen und der darin enthaltene Code ausgeführt.
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). |
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
Eine 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.
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 TemplateDocument 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 in einem Vorlagenfragment eine Variable vom Typ TemplateDocument ($CMS_SET(..., ...)$ hingegen nimmt eine Objektzuweisung vor). Das heißt, die Variable myVar ist in diesem Fall vom Typ TemplateDocument.
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!
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.
1. Beispiel: Erzeugung eines Sets
Ein Set (vgl dazu Seite Datentyp Set) kann wie folgt erzeugt werden:
$CMS_SET(BEZEICHNER, { })$Anschließend kann eine Zuweisung mit der Methode .add erfolgen.
Damit keine Ausgabe erfolgt, bietet sich eine $CMS_SET(...)$-Anweisung mit einer Dummy-Variable (z. B. void) an:
$CMS_SET(mySet, { })$
$CMS_SET(void, mySet.add("1. Eintrag"))$
$CMS_SET(void, mySet.add("2. Eintrag"))$
$CMS_SET(void, mySet.add("3. Eintrag"))$Die Ausgabe des Sets kann mithilfe einer $CMS_FOR(...)$-Anweisung realisiert werden:
$CMS_FOR(_wrapper, mySet)$
$CMS_VALUE(_wrapper)$
$CMS_END_FOR$
2. Beispiel: Erzeugung einer Liste
Mit einer $CMS_SET(...)$-Anweisung kann eine Liste erzeugt werden (vgl. dazu Seite Datentyp List).
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$
3. Beispiel: Setzen von sprachabhängigen Werten (Dictionary)
Ü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 eine Map):
$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:
$CMS_VALUE(langValues[#global.language.abbreviation]["value1"])$
4. Beispiel: Arbeiten mit Vorlagenfragmenten
Das Beispiel verdeutlicht den Umgang mit Variablen in unterschiedlichen Kontexten innerhalb einer Vorlage. 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(...)$). Ein solches Vorlagenfragment kann z. B. für das Füllen von Tabellenzellen verwendet werden.
Beispiel:
$CMS_SET(param, "Value A")$
$CMS_SET(set_param1)$
[Inside CMS_SET_BLOCK] $CMS_VALUE(param)$
$CMS_END_SET$
$CMS_SET(set_param2, " [Inside CMS_SET] " + param)$
$CMS_VALUE(set_param1)$<br>
$CMS_VALUE(set_param2)$<br>
$CMS_SET(param, "Value B")$
$CMS_VALUE(set_param1)$<br>
$CMS_VALUE(set_param2)$</br>
Ü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)$ durchlaufen.
Über die Anweisung $CMS_SET(set_param2, " [Inside CMS_SET] " + param)$ wird innerhalb der Vorlage die Variable set_param2 definiert und dieser der Wert der Variablen param zugewiesen (Objektzuweisung).
Die Ausgabe für das Beispiel lautet:
[Inside CMS_SET_BLOCK] Value A
[Inside CMS_SET] Value A
[Inside CMS_SET_BLOCK] Value B
[Inside CMS_SET] Value A
Innerhalb des $CMS_SET(...)$-Blocks ändert sich der Wert der Variablen (im Gegensatz zur Objektzuweisung über $CMS_SET(...)$), da hier der gesamte Rumpf des Vorlagenfragments bei jeder Auswertung der CMS_SET-Variable (etwa durch $CMS_VALUE(set_param1)$) durchlaufen und der darin enthaltene Code ausgeführt wird.
Im Gegensatz dazu wird der Wert für $CMS_SET(set_param2, " [Inside CMS_SET] " + param)$ nur einmalig zugewiesen und ändert sich anschließend nicht mehr.