5.5 Macros

This section lists the available macros in the Designer and describes how to use them.

Zegeba’s macros are different from our functions

Functions are executed whenever a referenced element is updated. On the other hand, macros are processed when the form loads and will not be re-run while the form is being filled out. They are often used to create expressions dynamically and can be placed in calculations in any element in the form or in rules.

Macros are constructed using element nodes. These work similarly to references but are specific for macros. At the end of the macro compilation all element nodes are converted to references that can be used in the functions as per normal. Element nodes cannot be created directly through drag & drop.

Macros can be either variables or functions:

1. Macro variables will be evaluated to some value based on the given expression
2. Macro functions will perform some operation and return the result; some with required input arguments, some without.

Important: since macros are processed when the form opens it is not possible to use a function as argument in a macro.

Macro functions

filterById

This macro performs a regex match on the element id of every element node given in the nodeList, the entries that match are returned. If matchType is set to the string REVERSE the elements not matching will be returned instead.

Parameters
nodeList – A list of node elements to filter.
regex – A regular expression given as a string value.
matchType – Set to the string literal REVERSE in order to return the entries that do not match, otherwise return the matches.

filterByType

This macro is similar to filterById, but instead of matching Element ID it matches the Element Type. The Element Type needs to be an exact match (e.g. single_select)

Parameters

nodeList – A list of node elements to filter.
nodeType – A string literal representation of the entry type.
matchType – Set to the string literal REVERSE in order to return the entries that do not match, otherwise return the matches.

listChildren

This macro returns an array of all element nodes that are descendants of parentNode, if all is not set to true only the direct children are returned, otherwise all descendants are returned (recursively).

Parameters
parentNode – The element node whose descendants we want to list.
all – Flag for whether we want all descendants or on the direct children, if this is set to false or omitted only the direct children will be returned.

listSiblings

This macro returns the list of siblings of the element this is used in as an array of element nodes. A sibling is an element that has the same direct parent.

nodeById

This macro returns the element node of the first form node with an element id equal to the given targetId,

Parameters
targetId – A string literal of the element id we want to find.

ResolveVariable

Element ID as a string [literal, string]

Macro variables

self

This variable evaluates to the element node of the form element for which the expression is being written. E.g. if you use this variable inside a calculation on the question “First Name” it will be evaluated to an element node representing “First Name”.