Calculation field

The value of an input field can be calculated automatically using formula expressions. Here, basic mathematical operations such as the sum or product are available as well as text concatenation or date operations.

images/download/attachments/44935340/image2019-12-4_10-29-12-version-1-modificationdate-1575451752232-api-v2.png

In the 'Calculations' property section, an input field can be changed to a calculation field by checking the 'Calculation field' checkbox (2). When the calculation field function is activated, additional fields and buttons are displayed:

(3) Change types: Defines when the calculation is to be triggered or executed again. This property refers to fields referenced in the Calculation expression (4), whose value change can retrigger the calculation.

(4) Calculation expression: Defines a formula to calculate the field value. Available functions (click on (5) or right click in the text field) can be nested as shown above. The screenshot shows a sample formula that adds the values of two fields with element IDs 3 and 4 and then multiplies them by 2 (2 * ( $el(3) + $el(4) ).

(5) A function can be selected here, which is then inserted at the current cursor position of the calculation expression field. Optionally, this can also be achieved by right-clicking at the corresponding position in the text field (see Berechnungsausdrücke).

(6) The expression is syntactically checked for correctness. Note: There is no check of the values or field contents here!

(7) Allows assigning a field value by inserting the $el function in the form $el( ElementID ) into the calculation expression at the current cursor position.


NOTE◄ Even if calculations are configured for an input field, it will still allow input as long as interactive access is not prevented via other options (not active, read-only, not visible). User input then competes with the calculation result, so the appropriate setting for the 'change types' is particularly important. In principle, this competition is a feasible way, e.g. to 'offer' calculated values to the user of a form, which he can then interactively override and then also save. In this case, however, the basic data (e.g. length, width, height), if any, no longer necessarily match the stored result value (e.g. volume <> length x width x height). Whether or when the calculation is to be triggered again in the event of new interactive changes to the basic data is governed by the 'Change types' for the calculation.

If special requirements for the calculation logic or the conditions for triggering recalculation in the workflow of a form cannot be covered with the given configuration options, the Calculate behaviour type offers additional design scope based on the same functions. On one hand, several behaviours with different calculation logics can be defined for the same target field, for example, which can be used in context or by case distinction. On the other hand, there is more control over when which calculation is performed and how the result is handled.

NOTE◄ The calculation functions are all visible and applicable both via Properties|Calculations and via Behaviour|Behaviour type|Calculate. However, some combinations are not useful. For example, the functions for data (arithmetic on date values) are not usable without comparison operation, i.e. cannot be used meaningfully for properties of a text field.

Available functions and syntax description

A detailed syntax description and all available functions can be found in the chapter Berechnungsausdrücke.

Application example

A text field is to set the doubled sum of the values of two text fields as the calculated value.

images/download/attachments/44935340/calculationField-version-2-modificationdate-1575452339971-api-v2.png
Image: Visually, in the form designer, the field is marked as a calculation field (calculator icon). The calculation expression corresponds to the formula 2*(a+b).

The screenshot below shows the form configured above at runtime.

images/download/attachments/44935340/image2018-5-25_15_28_2-version-1-modificationdate-1575451747854-api-v2.png

The third field immediately contains the result 14 after typing the number 4 into the field b (Element-ID 4).