Scripting

Mehr zum Thema Spreadsheets

Bevor sie diese Seite lesen, empfehlen wir folgende Seite zum Thema Spreadsheets sowie Spreadsheet-Funktionen zu lesen.

Für komplexere Umwandlungsaufgaben hat Synesty Studio die Scriptsprache Freemarkeropen in new window integriert, die es erlaubt komplexere Formeln, Funktionen und Logik auszuführen. Damit hat man die Möglichkeit, ähnlich wie mit Funktionen aus Tabellenkalkulationsprogrammen durch Bedingungen (if/else), Schleifen oder Manipulation von Zeichenketten Einfluss auf die Werte zu nehmen.

Folgende Funktionen (sog. Built-Insopen in new window oder Direktiven) werden am häufigsten benötigt:

Grundlagen

Im Mapper gibt es zwei Möglichkeiten einen Input Wert für eine Spalte festzulegen:

  • Quelle
  • Wert

Folgender Screenshot zeigt, wie ein Spaltenwert durch die Auswahlbox Quelle und einmal mit dem Value Feld gefüllt wird.

Scripting zur Manipulation von Spalten

Scripting ist hauptsächlich im Wert-Feld, aber auch im Skript-Feld anwendbar und erfolgt durch die Eingabe von sogenannten Freemarker Ausdrücken. 

Sonderfall: Skript-Feld

In den meisten Fällen werden sie das Wert-Feld verwenden. Das Skript-Feld ist nur eine Möglichkeit per Scripting den finalen Wert nach der Ausführung aller vorheriger Funktionen zu verändern. Im Skript-Feld steht der aktuelle Wert in Form der Variable ${value!} zur Verfügung.

Folgende Beispiele können mit unserem Beispiel-Spreadsheet open in new windowausprobiert werden.

Beispiel

${name}
 
<#if name?contains("a")>
 Die Spalte 'Name' beinhaltet ein A.
<#else>
 Es kommt kein A in der Spalte A vor. 
</#if>

Hinweis

Jeder Source-Spaltenname steht auch als Freemarker-Ausdruck für das Value-Feld zur Verfügung. Eine Liste verfügbarer Namen zum leichten Einfügen erhalten sie durch Klick auf das weißt Freemarker an null-Werteopen in new window als leeren String ('') darzustellen.

Manipulationen von Spalten

Hinweis

Alle folgenden Code-Beispiele beziehen sich auf das Wert-Feld einer jeden Spalte. Zum ausprobieren kopieren sie den entsprechenden Code-Block einfach in das Wert-Feld und drücken den Vorschau anzeigen Button.

String Manipulation

Freemarker besitzt viele sog. built-insopen in new window zur Manipulation von Strings, also Zeichenketten.

Folgender Ausdruck gibt unseren ${name!} in GROßBUCHSTABEN aus:

${name!?upper_case}

Das Fragezeichen ? wendet das  "built-in" upper_caseopen in new window auf die Variable name an.

Mehrere Funktionen gleichzeitig

Man kann mehrere Freemarker built-ins hintereinander hängen ("chain").

Beispiel: Nur den Text zwischen den Tags <p> und </p> ausgeben:

${"Test 123 <p>test</p>"?keep_after('<p>')?keep_before('</p>')}

Ausgabe: test

Zahlen Manipulation und Rechnen (arithmetische Funktionen)

Freemarker besitzt built-insopen in new window zur Manipulation von Zahlen.

${price?number?string.currency}

Die Ausgabe ist $42.00 Die verwendete Locale ist die des Servers, d.h. en_US. Das ?number Built-In ist notwendig, um aus einem String erst eine Zahl zu machen. Wenn die entsprechende Variable bereits eine Zahl ist, is ?number nicht notwendig.  Um den Preis in deutscher Locale auszugeben wäre es

<#setting locale="de_DE">
${price?number?string.currency} 

Die Ausgaben wäre bei de_DE 42,00 €

Punkt als Dezimaltrenner

Hinweis: Freemarker erwartet bei mathematischen Funktionen immer einen Punkt als Dezimaltrenner. D.h. falls Zahlen mit Komma als Dezimaltrenner existieren, muss das Komma erst durch einen Punkt ersetzt werden. Eine Möglichkeit wäre, dazu die ?replace Funktion zu benutzen:

${OrderTotalGross?replace(",",".")?number + OrderShippingCosts?replace(",",".")?number} 

Rechnen

Mit Freemarker kann man auch rechnen. Lesen Sie dazu mehr über arithmetische Funktionenopen in new window.

Beispiel:

${1 + 2}
# gibt 3 aus
 
${spalte1?number + spalte2?number}
# gibt die Summer von zwei Spalten aus.
 

Datumsfunktionen

Datumsmanipulationopen in new window ist auch mit Freemarker möglich.

<#assign purchaseDate = .now> 
${purchaseDate?string('yyyy-MM-dd HH:mm:ss zzzz')}

Ausgabe ist z.B. 2013-07-12 19:19:15 Central European Summer Time

Datumsangaben Vergleichen

Vergleich zweier Datumsangaben

<#if ("2020-12-11 20:09:42"?datetime('yyyy-MM-dd HH:mm:ss') > "2020-12-10 10:09:42"?datetime('yyyy-MM-dd HH:mm:ss')) >.
Das erste Datum ist neuer.
<#else>
Das erste Datum ist älter.
</#if>

Siehe dazu auch das Cookbook zu Datumsarithmetik / Rechnen mit Datumsangabenopen in new window.

Bedingungen / Boolean expressions (IF/ELSE)

Wenn/Dann Logik wird durch sog. Boolesche Ausdrücke realisiert. Damit lassen sich Spalteninhalte in Abhängigkeit von anderen Quellspalten manipulieren.

Zum Beispiel könnte man sagen, dass die Versandkosten 0 EUR betragen sollen, wenn der Preis größer 100 EUR ist. Ansonsten könnten die Versandkosten 5 EUR betragen.

Beispiel Versandkosten

<#if (price?number >= 100)>0 EUR<#else>5 EUR</#if>

Beispiel Prüfung, ob eine Zeichenkette ein bestimmtes Zeichen enthält

<#if name?contains('u')>
This is a name containing the letter 'u'
<#else>
No 'u' contained
</#if>

IF/ELSE mit String-Vergleichen:

<#if brandname! == ''>
Brandname is empty.
<#else>
${brandname!}
</#if>

Bei Vergleichen von Zeichenketten sollten Sie auf Leerzeichen achten und diese ggf. mit ?trim entfernen bzw. "wegschneiden".

<#if brandname!?trim == ''>
Brandname is really empty (spaces trimmed).
<#else>
${brandname!}
</#if>

Prüfen, ob Zeichenkette mit einem bestimmten Prefix startet (siehe starts_withopen in new window)

<#if brandname!?starts_with('myprefix')>
Yes, brandname starts with myprefix
<#else>
No, brandname does not start with the prefix.
</#if>

Zugriff auf Spalten / Variablen mit Sondernzeichen

Wenn man im Mapper mit Freemarker auf Spalten mit Sonderzeichen wie z.B. Bindestrich zugreifen will, dann muss man eine andere Syntax verwenden.

Beispiel:

${meine-spalte}

Dieser Ausdruck bringt Freemarker durcheinander, weil er denkt man müsste (in Worten) "meine minus spalte" rechnen.

Um mit Freemarker auf Variablen (Spalten) mit Sonderzeichen zuzugreifen kannst man eine andere Syntax verwenden z.B.:

${row["meine-spalte"]}

In der Variable ${row} (kommt von Synesty) sind alle Spalten enthalten und man kann mit eckigen Klammern darauf zugreifen.

Ausgeschlossene Freemarker Build-Ins und Direktiven

Es können nahezu alle Direktiven bzw. Build-Insopen in new window der Freemarker Version 2.3.29 verwendet werden. Aus Sicherheitsgründen gibt es einige, wenige Ausnahmen die hauptsächlich im Bereich "Seldom used and expert built-insopen in new window" zu finden sind.

Explizit ausgeschlossen sind die Build-Ins:

und die Direktiven: