Berechnungsausdruck
An einigen Stellen im Client können sogenannte Berechnungsausdrücke konfiguriert werden, um beispielsweise Beschriftungstexte oder andere Werte dynamisch zu berechnen.
Hierzu wird dem Konfigurator eine fest definierte Syntax zur Verfügung gestellt, welche unter anderem das Aufrufen von vordefinierten Funktionen oder das Einbinden von Konstanten ermöglicht.
Tipp: Um beliebige Rechnungen wie z.B. Multiplikation, Addition, etc. durchzuführen, kann die Funktion $calc() verwendet werden. Diese beachtet Grundrechenregeln wie "Punkt vor Strich" und Klammersetzung und bietet mathematische Standardfunktionen wie Wurzel, Sinus, Modulo etc. an.
In der Regel werden Werte, welche auch als Berechnungsausdruck ausgewertet werden können zur Konfiguration als spezielle Komponente angeboten, welche wie folgt aussieht.
(1) Ein Textfeld zum Eintragen des Berechnungsausdrucks
(2) Über den "Hinzufügen" 
Knopf können zur Verfügung stehende Konstanten und Funktionen ausgewählt werden. Beim Klicken erscheint ein Menü zur Auswahl der Bausteine. (Hinweis: Das gleiche Auswahlmenü erscheint auch als Kontextmenü des Textfeldes oder wenn "STRG/CMD + Leertaste" gedrückt wird.)
Die verfügbaren Ausdrücke (B) sind in logische Gruppen (A) unterteilt, um die Übersichtlichkeit zu wahren. Es werden direkt die Parameter der Funktionen und ihr Aufrufsyntax dargestellt. Parameter in eckigen Klammern sind dabei optional.
Durch das Auswählen eines Eintrags (B) wird dieser an der Stelle in das Textfeld eingefügt an welcher der Coursor zuletzt positioniert war.
(3) Mit dem "Überprüfen" ✔ Knopf kann die Syntax des Ausdrucks auf Korrektheit geprüft werden. Ebenso zeigt der erscheinende Dialog an, ob der Ausdruck in neuer einheitlicher Schreibweise dargestellt werden kann. Der Benutzer hat damit auch die Möglichkeit zu entscheiden, ob die vor Version 4.4.0 gültige Syntax durch den neuen Standard ersetzt werden soll (empfohlen).
(4) Öffnet einen grafischen Editor, zum visuellen Bearbeiten des Ausdrucks. Der grafische Editor bietet darüberhinaus auch Hilfestellungen zu Funktionen und Parametern an
(5) Bietet die Möglichkeit den Wert eines Formularelements in den Ausdruck einzubinden. Nur möglich, wenn die Berechnung im Kontext eines Formulars ausgewertet wird.
Syntax
Generell sieht die Syntax von Berechnungsausdrücken vor, dass Inhalt, welcher nicht der Ausdrucksyntax entspricht als Text interpretiert wird. Mit geschweiften Klammern kann immer auf Datenfelder des aktuellen Eingabeobjektes zugegriffen werden z.B. "{id}" oder "{value.textValue}".
Ebenfalls werden auch Funktionsaufrufe oder Konstanten automatisch als Ausdruck interpretiert (beginnend mit $):
$funktionsname( )
$konstantenname
Dabei ergibt beispielsweise "Wert: $konstante" die Ausgabe "Wert: WERT_DER_KONSTANTEN" und somit ergibt " $konstante" die Ausgabe " WERT_DER_KONSTANTEN" mit führendem Leerzeichen.
Hinweis: Diese Vereinbarung gilt rekursiv auch für die einzelnen Parameter von Funktionen.
Beispiele:
|
Syntax |
Erklärung |
|
$funktionsname(Parameter) |
Der Funktion "f" wird als Parameter das Wort "Parameter" übergeben |
|
$funktionsname($konstante) |
Der Funktion "f" wird als Parameter der Wert der Konstante übergeben |
|
$funktionsname({Parameter}) |
"Parameter" wird als Datenfeld des Eingabeobjektes ausgewertet und dessen gelesener Wert wird an die Funktion "f" als Parameter übergeben |
Achtung: Parameter werden wie oben erwähnt rekursiv der gleichen Logik folgend ausgewertet, was zu folgenden Fehlerquellen führen kann.
Gegeben sei eine Funktion $f(p), welche den Parameter p auswertet. Eine zweite Funktion $now( ) liefert hingegen einfach nur das aktuelle Datum als DateTime Objekt.
|
Syntax |
Mögliche Erwartungshaltung für p |
Tatsächlicher Wert von p |
Begründung |
|
$f($now()) |
Ein gültiges DateTime Objekt |
Wie erwartet ein gültiges DateTime Objekt |
$now( ) wurde ausgewertet und an $f(p) übergeben |
|
$f( $now() ) |
Ein gültiges DateTime Objekt |
Text: " [object Object] " |
$now( ) wurde zwar korrekt ausgewertet und lieferte ein gültiges DateTime Objekt zurück, allerdings wurde dieses Objekt dann mit einem führenden und endenden Leerzeichen konkateniert. Dazu musste das Objekt in einen Text umgewandelt werden. Da dies im Falle eines beliebigen Objektes nicht ohne weiteres Möglich ist, ergibt die Textrepräsentation "[object Object]" |
Steuerzeichen als Text ausgeben (Escaping)
Zusätzlich kann mit einem vorangestellten "\" (Backslash) ein beliebiges Zeichen von der Auswertung der logischen Ausdrücke ausgeschlossen und als normaler Text interpretiert werden.
Somit können beispielsweise auch "$" Zeichen in einen konstanten Text aufgenommen werden.
Beispiele:
|
Syntax |
Erklärung |
|
$funktionsname( ) |
Führt die Funktion "funktionsname" aus und schreibt den Rückgabewert in das Ergebnis |
|
\$funktionsname( ) |
Schreibt "$funktionsname( )" in das Ergebnis |
Zugriff auf Ressourcen (Einträge aus der Sprachverwaltung)
Zum Auflösen von Ressourcen wurde eine spezielle Ausdruckssyntax festgelegt, welche das Aufrufen einer separaten Funktion überflüssig macht:
Syntax:
[Bundle, Ressource,Standardwert,... Parameterliste]
Beispiel: [common, cancel]
Liefert den Wert "Abbrechen" aus der Sprachverwaltung.
Für Details siehe Zugriff auf Sprachverwaltungsresourcen (Berechnungsausdruck).
Zugriff auf Datenfelder
Über geschweifte Klammern {} können Werte aus Datenfeldern des Eingabeobjekts ($input) gelesen werden. Das Datenfeld kann auch als Pfad angegeben werden. Einzelne Datenfelder im Pfad werden mit "." voneinander getrennt (z.B. {datenfeldErstesLevel.datenfeldZweitesLevel.datenfeldDrittesLevel} ).
Tipp: Auf Listenelemente kann dabei der Index (beginnend bei 0) als Datenfeldname angegeben werden. z.B. datenfeldDerListe.3 → Liest den vierten Eintrag der Liste.
Für Details und Beispiele, siehe Zugriff auf Datenfelder in Berechnungsausdrücken.
Berechnungsausdrücke in Formularen
Wird ein Berechnungsausdruck im Kontext von Formularen ausgewertet, so können Werte von Maskenelementen direkt eingebunden werden.
Dies geschieht über eine Funktion namens "el".
Syntax:
$el(ElementId[, Duplikate])
Dabei wird als Parameter die entsprechende Element-ID übergeben, dessen Wert gelesen und zurückgeliefert wird. Im Falle eines Elementcontainers werden dessen Elementdaten zurückgeliefert.
Handelt es sich dabei um ein duplizierbares Element (z.B. innerhalb eines "Wiederholenden Elements"), so kann der zweite, optionale Parameter als "true" angegeben werden, um die Liste der Werte aller duplizierten Instanzen zu lesen (ehemals ALLFIELDS(element-id) ).
Tipp: Zusammen mit der Funktion "get" kann dabei einfach und bequem auf Datenfelder eines Elements oder eines beliebigen anderen Wertes zugegriffen werden.
Beispiel:
Ein Elementcontainer mit der Element-ID #6 beinhaltet die Daten welche weiter oben in diesem Kapitel als JSON vorgestellt wurden.
Beim Klicken auf einen Button "GET lastName" soll der Nachname der Person in einer Hinweisbox dargestellt werden.
Dafür wird dem Knopf ein Berechnen Verhalten angefügt, welches den folgenden Ausdruck auswertet:
$get($el(6),person.lastName)Als Aktion wird "Hinweis anzeigen" gewählt, deren Nachricht den Ausdruck "$input" (also den errechneten Wert des Verhaltens) auswertet und anzeigt.
Beim Drücken auf den Knopf erscheint wie erwartet ein Fenster, welches den Nachnamen "Abend" darstellt.
Verfügbare Konstanten und Funktionen
In den untergeordneten Seiten werden sämtliche zur Verfügung stehenden Funktionen und Konstanten aufgezählt und dokumentiert.