Expressions¶
Relevance, constraints and calculates all compute a new value using answers from other questions.
Syntax¶
| operator | usage | example | notes |
|---|---|---|---|
| this current prompt's answer | . | . < 5 | Constraint In a constraint, Dot (.) refers to the value in the current question.In this case it must be less than 5 |
| not | not(expression) | not(selected(${qname}, 'c')) | Relevant A question is relevant as long as 'c' is not selected in question qname |
| and | and | selected(., 'c') and selected(., 'd') | Constraint Both 'c' and 'd' need to be selected in the current question |
| or | or | selected(., 'c') or selected(., 'd') | Constraint Either 'c' or 'd' needs to be selected for the current question |
| greater than | > | . > 10.51 | Constraint Current question must be greater than 10.51. Can also be combined with equals to make "greater than or equal" >= |
| less than | < | . < 10.51 | Constraint Current question must be less than 10.51. Can also be combined with equals to make "less than or equal" <= |
| selected | selected(xpath/to/node, value) | selected(${qname}, 'n') | Relevant Checks if answer in selected prompt is selected Note xpath to node can be specified using ${} syntax with the question name |
| count-selected | count-selected(${multiple_choice_q}) | count-selected( . ) < 4 | Constraint The number of options selected in this question must be less than 4. |
| selected-at | selected-at(${multiple_choice_q}, index) | selected-at(${trips}, 0) | The first selected item will be at index 0, the second at index 1 etc |
| regular expression | regex(value, expression) | regex(., '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+.[A-Za-z]{2,4}') | Constraint This regex checks for a valid email address |
| equal to | . = | . = number('10') | Constraint Current answer must be equal to 10 |
| Conditional (if) | if(condition, a, b) If the condition is true use "a" otherwise use "b" |
if(${count} < 10, ${count}, 10) | Calculate If the count is less than 10 then use it.Perhaps as the number of times a repeat group is to be asked.Otherwise use the value 10.Hence this sets a cap on the value. |
Date Functions¶
| operator | usage | example |
|---|---|---|
| date formatted as text | format-date(${question}, format) Refer to the following section for a list of the date formats |
format-date(${dob}, '%Y %n %d') "2011 2 26" |
| Convert a date, or a time or a date and time to a decimal number | decimal-date-time(${question}) Useful as part of a date calculation.Every additional day adds one to the number Every additional hour adds 1/24 to the number |
Constraint decimal-date-time( . )> (decimal-date-time(${dob}) + 10.0416666) The entered date time must be more than 10 days and one hour after the date of birth. |
| Convert a date to a decimal number | decimal-date-time(${question}) Useful as part of a date calculation.Every additional day adds one to the number |
Constraint decimal-date( . )> (decimal-date(${dob}) + 10) The entered date must be more than 10 days after the date of birth. |
| Convert a time to a decimal number | decimal-time(${question}) Useful as part of a date calculation.Every additional hour adds 1/24 to the number |
Constraint decimal-time( . )>decimal-time(${time_of_birth}) + 10 div 24 The entered time must be more than 10 hours after the date of birth. |
| Convert a decimal number to a date | date-time(${question}) Convert a calculated date back into date format. |
Relevant date-time(decimal-date-time(${dob})+10) The date is equal to the date of birth plus 10 days. |
| Get todays date | today() | |
| Get current date and time. Use this instead of today() when setting the default values for date questions | now() | |
| Convert text to date | date('some text)' | constraint=". >= date('2011-11-12')" |
Date Formats¶
- %Y : 4 digit year
- %y : 2 digit year
- %m : numeric month padded with 0
- %n : numeric month
- %b : short text month (English)
- %d : day of month
- %H : hour, 24 hour clock padded with 0
- %h : hour, 24 hour clock
- %M : minute padded with 0
- %S : second padded with 0
- %3 : milliseconds padded with 0
- %a : short text day (English)
Text Functions¶
| Function | usage | example |
|---|---|---|
| Concatenate Text | concat(text1, text2, text3 etc) | concat(${name}, ${address}, ${city}) This joins the answers to the name, address and city question. Use it with a "calculate" question |
| Join Text | join(separator, text1, text2, text3 etc) This is the same as concatenate text except it adds the "separator" text between each of the items of text you are joining | join(';','Details',${name}, ${age}) If the value of name was "John Smith" and the value of age was "26" then this would set the value of a calculate question to: Details;John Smith;26 |
| Convert to number | number(${num-plots}) | |
| Convert to integer | int(${num-plots}) | |
| Convert to text | string(${num-plots}) | |
| Get the label for a choice in a select one question | jr:choice-name(${question name}, '${choice name}') | jr:choice-name(${transport_type}, '${transport_type}') Note the quotes around the second parameter |
| substring-before | substring-before(a, b) Returns everything in "a" before the text in "b" |
substring-before('xx-yy', '-') returns 'xx' substring-before(${q}, ' ') where ${q} has the value "Tom Smith", this will return "Tom" Available with fieldTask 5.90 |
| aubstring-after | substring-after(a, b) Returns everything in "a" after the text in "b" |
substring-after('xx-yy', '-') returns 'yy' substring-after(${q}, ' ') where ${q} has the value "Tom Smith", this will return "Smith" Available with fieldTask 5.90 |
| translate | translate(text, abc, XYZ) text The text to evaluate. abc The string of characters that will be replaced. XYZ The string of characters used for replacement. The first character inXYZwill replace every occurrence of the first character inabcthat appears intext. |
translate('My old car', 'old', 'new') will return 'My new car'. translate('My old car', 'olda', 'newx') will return 'My new cxr'. Available with fieldTask 5.90 The usage was taken from the following site which provides more information: https://developer.mozilla.org/en-US/docs/Web/XPath/Functions/translate |
| normalize-space | normalize-space(text) | Removes leading and trailing spaces from text and converts multiple spaces into a single space |
| Text Length | string-length(question) | string-length(.) < 5 Constraint The length of the text entered in the current question must be less than 5 characters |
Mathematical¶
Referring to data inside repeats, also called sub-forms, can be quite complex as you often need to identify which iteration of the sub form you are referring to. These functions can assist.
| operator | usage | example |
|---|---|---|
| Plus | ${a} + ${b} | |
| Minus | ${a} - ${b} | |
| Times | ${a} * ${b} | |
| Divide | div | ${a} div ${b} |
| Modulus Remainder | mod | 3 mod 2 Results in 1 |
| Raise to the power | pow(a,b) | pow(${width}, 3) Returns ${width} * ${width} * ${width} |
| Random number | random() Returns a random number between 0.0 (inclusive) and 1.0 (exclusive) |
round((random()* ${number_children} + 0.5), 0) Generates a random number between 1 and the number of children in the household. This can be used to select a child for further questions. (For examplle to select a child from a repeat group using the indexed-repeat() function: indexed-repeat(${child_name}, ${children}, round((random()* ${number_children} + 0.5), 0))) It can be combined with the position() function to display the name of the child that has been selected. |
| Round to a number of decimal places | round(a,b) Rounds the number a to the number of decimals places b |
round(${weight_kg}, 2) round(0.5, 0)is 1 |
| Sum of repeating group | sum(nodeset) | sum(${weight}) |
| Maximum | max(nodeset) | Maximum value in a repeating group |
| Minimum | min(nodeset) | Minimum value in a repeating group |
| digest | digest(data, algorithm, encoding method) | digest(${name}, 'SHA-1') Computes the hash of the data. This is useful if you do not want to store sensitive information on the server. The hash value of the data can be used as an alternative non identifying standin for the entered value. You can use the appearance phoneonly on the sensitive question so that it is not stored on the server. The options for the second parameter, algorithm, are 'MD5', 'SHA-1', 'SHA-256', 'SHA-384', 'SHA-512'. The third parameter, encoding method, is optional. By default 'base64' will be used. The options are 'base64', 'hex'. |
| sin | sin(45) | Returns the sine of the angle |
| cos | cos(45) | Returns the cosine of the angle |
| tan | tan(45) | Returns the tan of the number |
| asin | asin(45) | Returns the arc sine of the number |
| acos | acos(45) | Returns the arc cosine of the angle |
| atan | atan(${angle}) | Returns the arctan of the angle |
| atan2 | atan2(${y}, ${x}) | Returns the multivalued inverse tangent of y,x |
| sqrt | sqrt(${n}) | Returns the square root of the number |
| exp | exp(${x}) | Returns e to the power x |
| exp10 | exp10(${x}) | Returns 10 to the power x |
| pi | pi() | Returns an approximation of pi |
Repeats¶
Referring to data inside repeats, also called sub-forms, can be quite complex as you often need to identify which iteration of the sub form you are referring to. These functions can assist.
| operator | usage | example |
|---|---|---|
| reference a question inside a repeat group | indexed-repeat(${repeatquestion}, ${repeatgroup}, index) Index starts from 1 |
indexed-repeat(${name}, ${geopolygon_a}, 2) Returns the value for the name question in the second occurrence of the geopolygon_a repeat group. |
| Index of current repeat group | position(..) | indexed-repeat(${name}, ${names}, position(..)) Returns the name from the names repeat group at the same location index as the current repeat group. Note: .. Means go up one level. If your calculation is inside a group inside of a repeat then you will need to go up two levels using position(../..). and so on for as many nested groups that enclose the calculation. |
| Getting the number of repeats | count() | count(${repeat_name}) Returns the number of repeats |
Online¶
| Function | usage | example |
|---|---|---|
| lookup | This function can be used instead of pulldata in calculations. It takes the same parameters as pulldata. However the csv file is not downloaded. This can be useful when you have very large reference files. | lookup('hhdata','members','hhid_key',${hhid}) Not available in web forms |
| lookup_choices | This function can be used instead of the search() function. Both this and search() are placed in appearance. It takes the same parameters as search. However the csv file is not downloaded. This can be useful when you have very large reference files. | lookup_choices('children', 'matches', 'class_v', ${class}, 'enrolled_v', ${enrolled}) Not available in web forms |
| lookup_image_labels | lookup_image_labels(picture) This has no counterpart in offline mode. It can be used to call AWS Rekognition service to identify objects in a picture. Use in a calculation. The image must be a jpg file. To make this useful for your project you would probably want to create your own AI tool to recognise patterns in data and ask the fieldTask development team to add that as a service. |
lookup_image_labels(${a_picture}) Not available in web forms |
| get_media | Download a media file from a server. This media file can then be used as the default value for an image, video or audio question. Use in a calculation to set an image as an intial value to a question. | Use a select to identify a base image to be downloaded and then annotated. 1) Select a picture to edit. The value of the select is the URL of the image. 2) In a calculate have: get_media(${image_select_question}, '/main/image_show_question'). This will download the selected image 3) Have an image question with appearance of annotate" and a calculation of ${calculate_question_name}. Because of the way calculations are evaluated, when the user saves the form using the naive approach above will cause the modified image not to be sent. Refer to the dynamic image examples in the examples for an approach that will work." |
Other¶
| Function | usage | example |
|---|---|---|
| pulldata | pulldata(filename, data column, key column, key value) | pulldata('hhdata','members','hhid_key',${hhid}) This retrieves a value from the members column in the hhdata.csv file where the hhid_key column has the value selected for the hhid question. Available in webforms in version 18.05+ |
| coalesce | coalesce(value, value) | coalesce(${age}, 0) Coalesce returns the first non empty value out of the values provided in the parameters.This is useful when doing calculations with numbers as if a value was empty, perhaps because the question was not relevant, then the calculation will not work. In this example the age value is set to 0 if it is empty. |
| area | area(${the_geom}) Returns the area in square meters. Where the_geom is the name of a geoshape type question or a nodeset of geopoint questions. |
|
| distance | distance(${the_geom}) Returns the distance in meters of a nodeset of geopoint questions, or a line or the perimeter of a shape. |
|
| distance | distance(${q1}, ${q2}) Returns the distance in meters between two points |
|
| once | once(${age}) | The value will only be evaluated once while the form is open. This is useful for setting dynamic default values that you want to get an initial value but after that the value should be set by the user. |
| default | default(${age}) | The value will be evaluated every time the dependent questions change. In this example if the answer to the "age" question was changed then the value will be reset. However the value will not be re-evaulated on save of the form. Hence you can use this to allow the user to override a default value. Available with fieldTask 6.209 and above. |
| uuid | uuid(10) | Without the argument this returns an RFC4122 compliant unique number. Optionally an argument can be included to specify the length of the unique number. |
| boolean(arg) | boolean(arg) | Returns true if the argument is a number other than zero, a text string 1 or more characters in length, an expression that evaluates to true, or a non empty collection. Otherwise it returns false. |
| checklist(min, max, resp1, resp2 etc) | checklist(1,3, ${resp}) | Returns true if the number of responses that are exactly the string "yes" are between min and max |