Form Logic¶

Form logic building blocks¶

Variables¶

Variables reference the value of previously answered questions. To use a variable, put the question's name in curly brackets preceded by a dollar sign:

${question-name}

Variables can be used in label, hint, and repeat_count columns, as well as any column that accepts an expression.

XLSForm

survey¶

type	name	label
text	your_name	What is your name?
note	hello_name	Hello, ${your_name}.

Calculations¶

To evaluate complex expressions, use a calculate row. Put the expression to be evaluated in the calculation column. Then, you can refer to the calculated value using the calculate row's name.

Expressions cannot be used in label and hint columns, so if you want to display calculated values to the user, you must first use a calculate row and then a variable.

XLSForm

survey¶

type	name	label	calculation
decimal	bill_amount	Bill amount:
calculate	tip_18		round((${bill_amount} * 0.18),2)
calculate	tip_18_total		${bill_amount} + ${tip_18}
note	tip_18_note	Bill: $${bill_amount} Tip (18%): $${tip_18} Total: $${tip_18_total}

coalesce(${potentially_empty_value}, 0)

if(${potentially_empty_value}="", 0, ${potentially_empty_value})

Requiring responses¶

By default, users are able to skip questions in a form. To make a question required, put yes in the required column.

Required questions are marked with a small asterisk to the left of the question label. You can optionally include a required_message which will be displayed to the user who tries to advance the form without answering the question.

XLSForm

Setting default responses¶

To provide a default response to a question, put the response value in the default column.

Default values must be static values, not expressions or variables.

XLSForm

Validating and restricting responses¶

To validate or restrict response values, use the constraint column. The constraint expression will be evaluated when the user advances to the next screen. If the expression evaluates to True, the form advances as usual. If False, the form does not advance and the constraint_message is displayed.

The entered value of the response is represented in the expression with a single dot (.).

Constraint expressions often use comparison operators and regular expressions. For example:

. >= 18

True if response is greater than or equal to 18.

. < 20 and . > 200

True if the response is between 20 and 200.

regex(.,'p{L}+')

True if the response only contains letters, without spaces, separators, or numbers.

not(contains(., 'prohibited'))

True if the substring prohibited does not appear in the response.

XLSForm

Conditionally showing questions¶

The relevant column can be used to show or hide questions and groups of questions based on previous responses.

If the expression in the relevant column evaluates to True, the question or group is shown. If False, the question is skipped.

Often, comparison operators are used in relevance expressions. For example:

${age} <= 5

True if age is five or less.

${has_children} = 'yes'

True if the answer to has_children was yes.

Relevance expressions can also use functions. For example:

selected(${allergies}, 'peanut')

True if peanut was selected in the Multi select widget named allergies.

contains(${haystack}, 'needle')

True if the exact string needle is contained anywhere inside the response to haystack.

count-selected(${toppings}) > 5

True if more than five options were selected in the Multi select widget named toppings.

if(${a} != '' and ${b} != '', ${a} + ${b}, '')

Repeating questions and groups of questions¶

To repeat questions or groups of questions use the begin_repeat…end_repeat syntax.

XLSForm (Single question repeat)

XLSForm (Multi-question repeat)

Controlling the number of repetitions¶

User-controlled repeats¶

By default, the user controls how many times the questions are repeated.

Before each repetition, the user is asked if they want to add another repeat group.

Note

The label in the begin_repeat row is shown in the Add New Group? message.

A meaningful label will help enumerators and participants navigate the form as intended.

The user is given the option to add each iteration.

XLSForm

survey¶

type	name	label
begin_repeat	repeat_example	repeat group label
text	repeat_test	Question label
end_repeat

Note

This interaction may be confusing to users the first time they see it. If enumerators know the number of repetitions ahead of time, consider using dynamically defined repeats.

Statically defined repeats¶

Use the repeat_count column to define the number of times a group will repeat.

XLSForm

survey¶

type	name	label	repeat_count
begin_repeat	my_repeat	Repeat group label	3
note	repeated_note	These questions will be repeated as an entire group.
text	name	What is your name?
text	quest	What is your quest?
text	fave_color	What is your favorite color?
end_repeat

Dynamically defined repeats¶

The repeat_count column can reference previous responses and calculations.

XLSForm

survey¶

type	name	label	repeat_count
integer	number_of_children	How many children do you have?
begin_repeat	child_questions	Questions about child	${number_of_children}
text	child_name	Child's name
integer	child_age	Child's age
end_repeat

See also

Repeat Recipes and Tips

Filtering options in select questions¶

To limit the options in a select question based on the answer to a previous question, use a choice_filter row in the survey sheet, and filter key columns in the choices sheet.

For example, you might ask the user to select a state first, and then only display cities within that state. This is called a cascading select, and can be extended to any depth. This example form shows a three-tiered cascade: state, county, city.

XLSForm