Expressions (beta)

App spec expressions functionality is in beta testing and may be subject to change.

An expression is a special form of an attribute value. It is dynamically executed in the context of other fields and variables. A return value of the expression determines the value of the attribute.

Currently, expressions can be applied to the following attributes of the field:

Expressions can include field paths, variables, literals, operators. Expressions can be nested and can include other expressions.

Field paths

A field path can be used to access other field values within the expression. The path can be absolute or relative to the current execution scope.

Absolute path

An absolute field path is specified with the following form:

"$$<GLOBAL_SCOPE>.<field_key>"

Available global scopes for project fields:

$$PROJECT_FIELDS - contains values for all app setup fields of the project.

Available global scopes for event fields:

$$PROJECT_FIELDS - contains values for all app setup fields of the project.
$$EVENT_FIELDS - contains values for all event settings fields of the event.

Available global scopes for element fields:

$$PROJECT_FIELDS - contains values for all app setup fields of the project.
$$EVENT_FIELDS - contains values for all event settings fields of the event.
$$ELEMENT_FIELDS - contains values for all element custom fields of the element.

Available global scopes for question fields:

$$PROJECT_FIELDS - contains values for all app setup fields of the project.
$$EVENT_FIELDS - contains values for all event settings fields of the event.
$$ELEMENT_FIELDS - contains values for all element custom fields of the element.
$$QUESTION_FIELDS - contains values for all question fields of the element.

Available global scopes for option fields:

$$PROJECT_FIELDS - contains values for all app setup fields of the project.
$$EVENT_FIELDS - contains values for all event settings fields of the event.
$$ELEMENT_FIELDS - contains values for all element custom fields of the element.
$$QUESTION_FIELDS - contains values for all question fields of the element.
$$OPTION_FIELDS - contains values for all option fields of the element.

Examples of absolute field paths:

"$$PROJECT_FIELDS.appMode"
"$$PROJECT_FIELDS.footerEnabled"
"$$EVENT_FIELDS.IosVersion"

Relative path

A relative field path has the following form:

"$<field_key>"

The path is automatically resolved to the scope of expression execution. For example, if the expression is used on a top-level app setup field, the relative path "$appMode" is an equivalent of the absolute path "$$PROJECT_FIELDS.appMode".

Besides global scopes, there is also a collection item implicit scope. If an expression is used on a field in a collection item, relative field paths are resolved to fields of the same collection item.

Examples of relative field paths:

"$slideDisplayMode"
"$itemDisabled"

Field types and return values

Not all fields can be directly referenced with a field path.

Currently supported field types are:

Field type

Returned value type

freetext

string

list

string

boolean

number

For fields that support localisation, the value of the default locale is returned.

Variables

A variable can be specified to access project's related values within the expression. The variable can be absolute to the current execution scope only.

A variable contains a value of a specific type and is specified with the following form:

"$$<VARIABLE_PATH>"

Variable can be nested. In that case, variable path contains . as a separator.

Built-in variables

The following built-in variables are defined:

$$PROJECT_ELEMENTS - an object containing project element attributes grouped by element's content_type. An attribute can be accessed with the following syntax:

"$$PROJECT_ELEMENTS.<element_content_type>.<attribute>"

Attribute

Type

Description

visible

boolean

Return true if element is enabled on

Example:

mandatory": { 
  "$eq": ["$$PROJECT_ELEMENTS.rpoll-custom.visible", false] 
}

Literals

Literals are static values that can be used in comparison expressions.

Literal type

Examples

number

123

3.14

string

"some string"

boolean

true

false

Operators

An expression operator has the following form:

"<operator>": [<argument1>, <argument2>...]

The argument of an operator is another expression - literal, operator, field path etc.

Operator

Description

Arguments

Return value

$eq

Checks if all arguments are equal

Count: 2+ All arguments must be of the same type.

boolean

$ne

Checks if any argument is not equal to others

Count: 2+ All arguments must be of the same type.

boolean

$or

Checks if any argument is true

Count: 2+ All arguments must be of a boolean type.

boolean

$and

Checks if all arguments are true

Count: 2+ All arguments must be of a boolean type.

boolean

Examples

A field is mandatory if language_selector_position field has value "left".

"mandatory": { 
  "$eq": ["$$PROJECT_FIELDS.language_selector_position", "left"] 
}

A field is visible if banner_left_enabled has value true or banner_right_enabled has value true. In other words, a field is visible if at least one of the boolean fields is true.

"visible": {
  "$or": [
    { "$eq": ["$$PROJECT_FIELDS.banner_left_enabled", true] },
    { "$eq": ["$$PROJECT_FIELDS.banner_right_enabled", true] },
    { "$eq": ["$$PROJECT_ELEMENTS.rpoll-custom", true] }
  ]
}

A field is mandatory in a collection item if has_title field of the same collection item is true.

"mandatory": {
  "$eq": ["$has_title", true]
}

A field is visible if poll element is enabled in Project Settings.

"visible": { 
  "$eq": ["$$PROJECT_ELEMENTS.poll.visible", true] 
}