Calculation expression
So-called calculation expressions can be configured at some points in the client, for example to calculate label texts or other values dynamically.
The configurator is provided with a predefined Syntax for this purpose, which enables predefined functions to be called or constants to be integrated, among other things.
Tip: The $calc() function can be used to perform any calculations such as multiplication, addition, etc.. This observes basic arithmetic rules such as “ decimal point before dash” and bracketing and offers standard mathematical functions such as square root, sine, modulo, etc.
As a rule, values which can also be evaluated as a calculation expression are offered for configuration as a special component, which appears as follows.
(1) A text field for entering the calculation expression.
(2) Via the 'Add' 
button, available constants and functions can be selected. When clicked, a menu for selecting the blocks appears. (Note: The same selection menu also appears as a context menu of the text field or when 'CTRL/CMD + space bar' is pressed.)
The available expressions (B) are divided into logical groups (A) for clarity. The parameters of the functions and their call syntax are displayed directly. Parameters in square brackets are optional. Selecting an entry (B) inserts it into the text field at the position where the cursor was last positioned.
(3) With the 'check' ✔ button, the syntax of the expression can be checked for accuracy. The dialog that appears also indicates whether the expression can be displayed in 'new uniform notation'. The user can also decide whether the syntax valid before version 4.4.0 should be replaced by the new standard (recommended).
(4) Opens a graphical editor for visual editing of the expression. The graphical editor also offers help on functions and parameters.
(5) Offers the possibility to include the value of a form element in the expression.
►NOTE◄ This is only possible if the calculation is evaluated in the context of a form.
Syntax
In general, the syntax of calculation expressions provides that content to be evaluated as an expression is written in curly brackets '{expression}'. If the brackets were omitted, the word 'expression' would be returned unchecked as text. e.g. "{id}" or "{value.textValue}".
Function calls or constants are also automatically interpreted as expressions (starting with $):
$funktionsname( )
$konstantenname
For example, 'Value: $konstante' results in the output 'Value: VALUE_OF_CONSTANTS' and thus '$constant' results in the output 'VALUE_OF_CONSTANTS' with leading blank characters.
►NOTE◄ This agreement also applies recursively to the individual parameters of functions.
Examples:
|
Syntax |
Explanation |
|
$functionsname(Parameter) |
The function 'f' passes the word 'parameter' as the parameter. |
|
$functionsname($constant) |
The function 'f' passes the value of the constant as the parameter. |
|
$functionsname({Parameter}) |
'Parameter' is evaluated as a data field of the input object and its read value is passed to the function 'f' as the parameter |
►CAUTION◄ As mentioned above, parameters are evaluated recursively following the same logic, which can lead to the following sources of error.
In this examples a function $f(p) is used, which evaluates the 'p' parameter. A second function $now( ) simply returns the current date as DateTime object.
|
Syntax |
Possible expectations for p |
Actual value of p |
Explanation |
|
$f($now()) |
A valid DateTime object |
An expected valid DateTime object |
$now( ) was evaluated and passed to $f(p) |
|
$f( $now() ) |
A valid DateTime object |
Text: '[object Object]' |
$now( ) evaluated correctly and returned a valid DateTime object, but this object was concatenated with a leading and trailing space. Therefore the object has to be converted into a text. Since this is not easily possible in the case of any object, the text representation '[object Object]' results |
Transfer control characters as text (Escaping)
Additionally, with a prefixed '\' (backslash), any character can be excluded from the evaluation of the logical expressions and interpreted as normal text.
For example, '$' characters can be included in a constant text.
Examples:
|
Syntax |
Explanation |
|
$funktionsname( ) |
Executes the function 'functionname' and writes the return value into the result |
|
\$funktionsname( ) |
Writes '$function name( )' in the result |
Access to resources (entries from language administration)
A special expression syntax has been defined for resolving resources, which makes it unnecessary to call a separate function:
Syntax:
[Bundle, resource, default... Parameterlist]
Example: [common,cancel]Returns "Cancel".
For details, see Access to localized resources (Calculation expression).
Access to data fields
Values can be read from data fields of the input object ($input) via curly brackets {}. The data field can also be specified as a path. Individual data fields in the path are separated from each other with '.' (e.g. {data fieldFirstLevel.data fieldSecondLevel.data fieldThirdLevel} ).
Tip: For list elements, the index (starting with 0) can be specified as the data field name. e.g. data fieldTheList.3 → Reads the fourth entry of the list.
For more details and examples, see also Access to data fields in calculation expressions.
Calculation expressions in forms
If a calculation printout is evaluated in the context of forms, the values of form elements can be included directly. This is done using a function called 'el'.
Syntax:
$el(ElementId[, Duplikate])
The corresponding element ID is passed as a parameter, whose value is read and returned. In the case of an element container, its element data is returned. If this is a duplicate element (e.g. within a Wiederholenden Elements), the second, optional parameter can be specified as 'true' to read the list of values of all duplicated instances (formerly ALLFIELDS(element-id) ).
Tip: Together with the 'get' function, data fields of an element or any other value can be accessed easily and conveniently.
Example:
An element container with element ID #6 contains the data presented earlier in this chapter as JSON. When clicking on a button 'GET lastName' the last name of the person is displayed in a message box. For this purpose, a Calculate behaviour is added to the button, which evaluates the following expression:
$get($el(6),person.lastName)As an action, 'Show alert' is selected, and the message evaluates and displays the expression '$input' (the calculated value of the behaviour).
When you press the button, a window appears which displays the surname 'Abend'.
Available constants and functions
All available functions and constants are listed and documented in the child pages.