Skip to content

Commit 6cfa5b0

Browse files
AmandaJ-WAmandaJ-W
authored
Create constraints_xls.md
1 parent a0ade43 commit 6cfa5b0

File tree

1 file changed

+107
-0
lines changed

1 file changed

+107
-0
lines changed

‎source/constraints_xls.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Adding constraints in XLSForm
2+
3+
Constraints, also known as validation criteria, are a type of form logic used to **restrict the acceptable responses to a question based on a predefined condition**. If the constraint condition is not met, a customizable error message is displayed, prompting the form user to enter a valid response.
4+
5+
<p class="note">
6+
To learn more about form logic in XLSForm, see <a href="https://support.kobotoolbox.org/form_logic_xls.html">Introduction to form logic in XLSForm</a>.
7+
</p>
8+
9+
This article covers the following topics:
10+
- Adding constraints to questions in XLSForm
11+
- Combining multiple constraint conditions
12+
- Customizing constraint error messages
13+
- Advanced constraints in XLSForm
14+
15+
<p class="note">
16+
<strong>Note:</strong> This article focuses on adding constraints in <a href="https://support.kobotoolbox.org/getting_started_xlsform.html">XLSForm</a>. To learn about adding constraints in the KoboToolbox Formbuilder, see <a href="https://support.kobotoolbox.org/validation_criteria.html?highlight=limiting">Adding validation criteria in the Formbuilder</a>.
17+
<br><br>
18+
For hands-on practice with adding constraints in XLSForm, see KoboToolbox Academy’s <a href="https://academy.kobotoolbox.org/courses/xlsform-fundamentals">XLSForm Fundamentals Course</a>.
19+
</p>
20+
21+
## Adding a constraint
22+
23+
Constraints are built using [question references](https://support.kobotoolbox.org/form_logic_xls.html#question-referencing), [comparison operators](https://support.kobotoolbox.org/form_logic_xls.html#mathematical-and-comparison-operators), and constants. Constraint conditions must be met to validate or submit a form. Otherwise, an **error message** appears, and users are prevented from moving to the next page or submitting the form.
24+
25+
To add constraints in XLSForm:
26+
1. Add a **constraint** column to the `survey` worksheet.
27+
2. In the `constraint` column, define the condition that must be met **for the response to be valid.**
28+
- Use a period `.` to reference the question in the row where you are adding a constraint.
29+
- Use a [comparison operator](https://support.kobotoolbox.org/form_logic_xls.html#mathematical-and-comparison-operators), followed by a reference value, to build a simple constraint.
30+
- For example, `. > 18` restricts an `integer` question to accept only values greater than 18.
31+
32+
**survey worksheet**
33+
34+
| type | name | label | constraint |
35+
|:---------|:-----------|:-------------------------------------|:----------------|
36+
| integer | age | What is your age? | . >= 18 |
37+
| integer | household | How many people live in your household? | . <= 30 |
38+
| integer | income | Out of those, how many earn income? | . <= ${household} |
39+
| survey |
40+
41+
### Formatting reference values
42+
The reference value in a constraint condition must match the **type** of the question for which you are adding a constraint. The reference value formats for main question types are listed below:
43+
44+
| Question type | Reference value format | Example |
45+
|:----------------|:-----------------------------------------------------------|:------------------------------|
46+
| integer | Number | `. > 35` |
47+
| select_one | Choice name (as defined in the choices worksheet) in quotation marks | `. = 'yes'` |
48+
| select_multiple | Choice name combined with the `selected()` <a href="https://support.kobotoolbox.org/functions_xls.html">function</a> | `selected(., 'chair')` |
49+
| date | Date in the `date('YYYY-MM-DD')` format | `. > date('2021-01-01')` |
50+
| text | Text in quotation marks (rarely used for constraints) | `. != 'Not applicable'` |
51+
52+
<p class="note">
53+
To learn more about building form logic expressions in XLSForm, see <a href="https://support.kobotoolbox.org/form_logic_xls.html">Introduction to form logic in XLSForm</a>.
54+
</p>
55+
56+
## Combining multiple constraint conditions
57+
Multiple constraint conditions can be combined into a single expression to determine whether a response is valid. Conditions can be combined using **and**, **or**, and **not** logical operators:
58+
59+
- Use **and** when all conditions must be met for a response to be valid.
60+
- For example: <code>. > 18 <strong>and</strong> . < 65</code>
61+
- Use **or** when at least one condition must be met for a response to be valid.
62+
- For example: <code>. < 18 <strong>or</strong> ${student} = 'yes'</code>
63+
- Use **not** to indicate that a condition or set of conditions must not be met (e.g., when two conditions cannot be true together for a response to be valid).
64+
- For example: <code><strong>not</strong>(. < 18 <strong>and</strong> ${household_head} = 'yes')</code>
65+
66+
**survey worksheet**
67+
68+
| type | name | label | hint | constraint |
69+
|:---------|:-------|:------------------|:--------------------------------------------|:---------------------------------------------------------|
70+
| integer | age | What is your age? | Must be less than 18 or above 65 to participate | <code>. < 18 <strong>or</strong> . > 65</code> |
71+
| integer | weight | How much do you weigh? | Must be between 30 and 200 kg | <code>. >= 30 <strong>and</strong> . <= 200</code> |
72+
| survey |
73+
74+
75+
## Customizing constraint error messages
76+
77+
By default, when a response value in the form does not meet the constraint condition, a “Value not allowed” error message appears. It is recommended to customize this message to inform users why the value is invalid, allowing them to correct their input.
78+
79+
To customize the constraint error message:
80+
1. Add a **constraint_message** column to the `survey` worksheet.
81+
2. In the `constraint_message` column, enter the text you wish to display as the error message when the constraint conditions are not met.
82+
83+
**survey worksheet**
84+
85+
| type | name | label | constraint | constraint_message |
86+
|:--------|:-----|:----------------|:-----------|:----------------------|
87+
| integer | age | What is your age? | . >= 18 | Must be older than 18. |
88+
89+
## Advanced constraints in XLSForm
90+
91+
Beyond basic constraints, you can customize conditions to ensure data quality and adapt to many data collection scenarios. To build more advanced constraint conditions in XLSForm:
92+
93+
- Use parentheses to combine more than two conditions
94+
- Use [functions](https://support.kobotoolbox.org/functions_xls.html) for increased flexibility
95+
- Use [regular expressions](https://support.kobotoolbox.org/restrict_responses.html) to restrict text responses
96+
97+
Examples of more advanced validation criteria include:
98+
99+
| Criteria | Description |
100+
|:---------|:------------|
101+
| <code>(. >= 18 and . < 130) or (. = 999)</code> | The response must be between 17 and 130 or be equal to 999 (often used for non-response) |
102+
| <code>not(${in_university} = 'yes' and . < 16)</code> | If the answer to `in_university` is ‘yes’, the current response must be greater than 16. |
103+
| <code>not(selected(., 'none') and count-selected(.)>1)</code> | The ‘none’ option cannot be selected if any other response in a `select_multiple` question is selected. |
104+
| <code>. < today()</code> | The date entered must be before today’s date. |
105+
| <code>regex(., '^\d{2}$')</code> | The input is restricted to two numbers (using <a href="https://support.kobotoolbox.org/restrict_responses.html">regular expressions</a>). |
106+
107+

0 commit comments

Comments
 (0)