Module field expressions

Module field expressions enable support for arbitrary expressions on module fields. Module field expressions allow us to implement value expressions (formula fields), custom sanitizers, and custom validators.

Expressions are evaluated using gval with a wrapper pkg/expr package, which enables two essential bits:

These expressions can be ran in a JavaScript environment (in the front-end applications).
These expressions are evaluated close to the core, reducing overhead; increasing stability and performance.

Field expressions can only access data from the current record; they can not traverse references.

Value expressions (formula fields)

Value expressions calculate the field value from the context (the rest of the record). Value expressions remove the need for automation scripts that do simple calculations.

Fields that define a value expression, ignore any user input.

Value expression evaluation errors are appended to the field error set.

If a module field is a multi-value field, the expression must return an array.

Available variables in the evaluation context:

old: record object with old values (empty when creating).
new: record object with current field values.
<field-name>: a string or array of strings with current field values.

If field name collides with any of reserved variables it can be accessed via old.values.<field-name>.

Sanitizers

Sanitizers modify the field value to cleanup (sanitize) the data before it is saved. Sanitizers can only modify values, and can not raise errors.

Custom sanitizers are run before built-in sanitizers; the built-in sanitizers can not be disabled. If there are multiple sanitizers, they are run in the defined order.

Sanitizer evaluation errors are logged in the action log.

Available variables in the evaluation context:

value: the current field value.

Validators

Validators validate the field value by raising errors when the value is not valid. Validators can not change the value.

Custom validators are ran after or instead of built-in validators, and before unique value checks.

Built-in field validators can be disabled; required and unique-multi-value validators can not be disabled.

If there are multiple validators, they are run in the defined order. The field validation step errors out when first error occurs. If we define validators A, B, and C, and the validator A raises an error; validators B and C are not evaluated.

Validation expressions are not executed when:

the value is not changed,
the value is missing.

Use the required flag to check for required values.

Available variables in the evaluation context:

value: the current field value,
oldValue: the old field value,
values: all current field values (values.<field-name>).