5.4 List of functions
Note: the content here is intended for advanced users with a good technical understanding of functions. Please contact Zegeba if you need help.
aggregatedRepeatSum
This function is used to get the aggregated sum of every answer given to an element, subElementID, in the repeat repeatReference.
Parameters
repeatReference – A reference to the repeat element whose answers we want to aggregate data from.
subElementID – The ElementID of the element in the repeat that we want to sum all answers from.
concatenateRepeatAnswers
repeatReference – A reference to the repeat element whose answers we want to aggregate data from.
subElementID – The ElementID or ElementIDs (array) of which we want o concatenate answers across all repeat rows.
outerDelimiter – The delimiter to use as separator between data from repeat rows.
innerDelimiter – The delimiter to use as separator between each of the elementIDs within a repeat row.
This example takes the first and last names entered in a repeat and creates a string of all of names entered. First and last names are separated by a comma and each person is separated by a pipe character (|).
If we enter the names Ada Bulghur, Colin Draper, Eamonn Frostad in 3 repeat instances, this function will give us the concatenated text string Ada,Bulghur|Colin,Draper|Eamonn,Frostad
This string may then be copied to other software.
contains
This function checks if haystack contains needle, if so, returns true.
Parameters
haystack – A reference to an element with a string or array answer. Or a string or array value.
needle – A reference to an element with a string or numeric answer. Or a string or number.
countCorrectRepeatAnswers
This function is used to count the number of repeat instances in which an element has the given correctAnswer. This works the same as countCorrectRepeatAnswersFakeArray but only accepts a single correct answer.
Parameters
repeatReference – A reference to the repeat element whose answers we want to check.
subElementID – The ElementID of a Single Select element in the repeat whose answers we want to check.
correctAnswer – The valid answers for subElementID.
Example
We want to now how many people who register in a form is called Eve. The repeat (left) and the formula (right) in the element Count correct repeat answers look like this:
countCorrectRepeatAnswersFakeArray
This function is used to count the number of repeat instances in which an element has an answer from a listing of correct answers.
Parameters
repeatReference – A reference to the repeat element whose answers we want to check.
subElementID – The ElementID of the element in the repeat whose answers we want to check.
correctAnswers – A listing of valid answers for subElementID. The list is made up of a string of elements separated by spaces ( ). e.g. “valid1 valid2 valid3”.
countValuesIf
This function counts how many of the listed references have a value matching targetValue. criterion can be set to EQUAL in order to count the ones that match, otherwise the ones that differ will be counted.
Parameters
references – An array of references that we want to check.
criterion – Flag for whether we want to count answers that are equal to targetValue or differs. If this is set to the string literal EQUAL matching elements will be counted, otherwise the ones not matching will be counted.
targetValue – The literal value we want to compare to, type depends on the type of the element.
formatDateTime
This Date and Time function returns a string representation of a point in time in the provided moment.js format.
Parameters
dateTime – A reference to an element with a date or dateTime answer.
format – The desired moment.js formatting.
formatDuration
This Date and Time function allows for a number of seconds to be formatted into a human readable format. The default format is: Y [year(s)] M [month(s)] D [day(s)] H [hour(s)] m [minute(s)] s [second(s)]. (You can copy this string into the field.) Empty values are trimmed for the default format, and any leading empty values will be trimmed in general. e.g. 0 yr, 0 day, 2 min, 0 sec would be trimmed to 2 min, 0 sec when using a custom format. Using the default format 0 sec would also be trimmed.
Enclosing values in square brackets [] will cause them to remain as is. For instance, if you type why, this will be processed since w, h and y are all variables (weeks, hours, years). On the other hand, [why] will remain as why in the output.
Available formatting variables (see plugin github page for further documentation):
| ELEMENT | FORMAT |
|---|---|
| years | Y or y |
| months | M |
| weeks | W or w |
| days | D or d |
| hours | H or h |
| minutes | m |
| seconds | s |
| ms | S |
Parameters
numberOfSeconds – this is the number of seconds to format, to get the value of a number element a reference should be used.
format – a string representing the desired formatting. See above for available variables. Set to default for default format.
getFormSaveCount
Counts the number of forms saved locally on the device using the Forms or Web app.
iif
This function (Immediate If) decides if an expression is true or false according to a user input. It returns one value if the expression is true, another if it is false. Conditions can be nested to give more that two answers. As the Zegeba Rule Editor does not contain an action for SET; IF… THEN … SET ….) that sets a value when a condition is met, the iif function can be used instead.
The following example evaluates scores and assigns a grade in a Text Input element. Scores lower than or equal to 1 are Grade 1, between 1 and 2 are Grade 2, higher than 2 are Grade 3. The grades 1-3 are the answers in this nested calculation and will be written in the Text Input element.
Iif can also be used to send email notifications to different users based on the form state of the report. See an example of this in Designing: 8.2 Automatic email notifications with PDF reports and form links.
Parameters
expr – the value of an expression that is true or false.
ifTrue – the value to be returned if expression is true.
ifFalse – the value to be returned if expression is false.
length
This function returns the length of a value. If the value is a boolean (a true/false variable), 0 is returned. If value is an array, the number of elements is returned. If value is a string or number, the number of characters in it is returned.
Length can be used to check if an element has been answered. E.g. if you calculate the length Signature element, you’ll see that it has been answered (signed) if the length > 0.
Parameters
value – A reference to an element whose answer we want to get the length of.
max
This function returns the largest value between a and b.
Parameters
a – A reference to an element whose answer we want to compare or a string/numeric value.
b – A reference to an element whose answer we want to compare or a string/numeric value.
min
This function returns the smallest value between a and b.
Parameters
a – A reference to an element whose answer we want to compare or a string/numeric value.
b – A reference to an element whose answer we want to compare or a string/numeric value.
modulo
Element Reference – [path,literal,string].
notContains
This function checks if the haystack does not contain a needle, if so, returns true. In other words, the opposite of contains.
Parameters
haystack – A reference to an element with a string or array answer. Or a string or array value.
needle – A reference to an element with a string or numeric answer. Or a string or number.
notStartsWith
This function checks if haystack does not start with needle, if so returns true. For haystacks that are strings this means we check if the string starts with needle, for arrays this means that the first element is needle.
Parameters
haystack – A reference to an element with a string or array answer. Or a string or array value.
needle – A reference to an element with a string or numeric answer. Or a string or number.
now
This function returns the current date and time. It can be used to compare date/time relative to the current moment in time.
processDescriptionTemplate
This function finds the current value of a text description formula, such as {#abc} or {$form.name}.
The parameter must be a static string and not the result of other functions.
Parameters
descriptionFormula – A code in brackets {}.
queryContext
This function returns a value from the data instance’s context object if found. Multi-level properties can be accessed by using a . (full stop) as the separator, e.g. project.location.address
Parameters
key – The key of the context entry we want to return.
rand
This function returns a random number (integer) between min and max.
Parameters
min – a integer number: the lower bound (inclusive) of the range of the generated value.
max – a integer number: the upper bound (inclusive) of the range of the generated value.
regexMatches
This function returns a boolean value indicating if the input is a match with accordance to the supplied regex. (Implemented using RegExp.prototype.test)
Parameters
input – A reference to an element with a string answer. Or a string value.
regex – A regular expression given as a string value. The regex is processed with no flags set.
regexReplaceAll
This function performs a global regex replace on the input string. (Implemented using String.prototype.replace)
Parameters
inputString – A reference to an element with a string answer. Or a string value.
regex – A regular expression given as a string value. The regex is processed using the g flag.
replacement – The string to replace all matches with.
repeatIncrement
This function will return the highest current value of subElementID in a repeat +1. In other words, it will return the next sequence number for subElementID across all answer sets in that element’s parent repeat. It is meant to be used for auto incrementing a value on a repeat for every repeat instance. Add a number element to a repeat and set its calculation to be repeatIncrement() with the ElementID of the element itself as the parameter.
Parameters
subElementID – The ElementID of the number element on a repeat you want the next value of.
round
This function rounds a number to the given number of digits.
Parameters
number – A reference to a decimal element or value that we want to round off.
digits – The desired number of decimals we want in the returned number.
startsWith
This function checks if haystack starts with needle, if so returns true. For haystacks that are strings this means that we check if the string starts with needle, for arrays this means that the first element is needle.
Parameters
haystack – A reference to an element with a string or array answer. Or a string or array value.
needle – A reference to an element with a string or numeric answer. Or a string or number.
startsWithAnyOf
This function checks if haystack starts with needle, if so returns true. For haystacks that are strings this means that we check if the string starts with needle, for arrays this means that the first element is needle.
Parameters
haystack – A reference to an element with a string or array answer. Or a string or array value.
needle – A reference to an element with a string or numeric answer. Or a string or number.
sumCorrectRepeatAnswers
This function is used to calculate the sum of numeric values when a specific answer is given to another element in the repeat. The other element can be a Text Input, Number, Decimal, Single or Multiple Select element.
Parameters
repeatReference – A reference to the repeat element whose answers we want to check.
subElementID – The ElementID of an element in the repeat whose answers we want to check.
correctAnswer – The valid answers for subElementID.
elementToCountElementID – The Element ID of the numeric element inside the repeat we want to sum across all instances where correctAnswer is selected.
Example
We want a sum of the ages of all females who register in a form. The repeat (left) and the formula (right) in the element Sum correct repeat answers look like this:
If we wanted to for instance only count the ages of females aged 20 or more, we would have to create a separate hidden calculation for this and then put that element as the bottom one in the formula instead of “age”. We can also combine this function with countCorrectRepeatAnswers (see example above), for instance to count only the age of females called Eve.
SumNumbers
Parameters
references – The list of references to number of decimal elements to sum.
today
This function returns the current date with the time set to 00:00. It can be used to compare date/time elements/answers to the start of the current day.
