Skip to content

Commit a0ade43

Browse files
AmandaJ-WAmandaJ-W
authored
Create skip_logic_xls.md
1 parent 3e3826b commit a0ade43

File tree

1 file changed

+110
-0
lines changed

1 file changed

+110
-0
lines changed

‎source/skip_logic_xls.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Adding skip logic in XLSForm
2+
3+
Skip logic, also known as relevance logic, allows you to **determine when a question or group of questions will be displayed** in the form based on a previous question or the result of a calculation. For example, you can use it to ask follow-up questions only to a subset of respondents, or to hide entire sections of a form if they are not relevant.
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 skip logic to individual questions
11+
- Combining multiple skip logic conditions
12+
- Adding skip logic based on whether a question was answered
13+
- Adding skip logic to question groups
14+
15+
<p class="note">
16+
<strong>Note:</strong> This article focuses on adding skip logic in <a href="https://support.kobotoolbox.org/getting_started_xlsform.html">XLSForm</a>. To learn about adding skip logic in the KoboToolbox Formbuilder, see <a href=https://support.kobotoolbox.org/skip_logic.html">Adding skip logic in the Formbuilder</a>.
17+
<br><br>
18+
For hands-on practice with skip logic in XLSForm, see KoboToolbox Academy’s <a href="https://academy.kobotoolbox.org/courses/xlsform-fundamentals">XLSForm Fundamentals Course</a>.
19+
</p>
20+
21+
## Adding skip logic conditions to individual questions
22+
23+
Skip logic uses [question referencing](https://support.kobotoolbox.org/form_logic_xls.html#question-referencing) to only display questions that are relevant to the respondent based on previous answers. The question used to define the relevance logic is referred to as the **reference question**.
24+
25+
To add skip logic in XLSForm:
26+
1. Add a **relevant** column to the `survey` worksheet.
27+
2. In the row of the question you wish to display or hide, enter the condition that must be met **for the question to be displayed.**
28+
29+
**survey worksheet**
30+
31+
| type | name | label | relevant |
32+
|:--------------|:----------|:------------------|:--------------|
33+
| integer | age | How old are you? | |
34+
| select_one yn | married | Are you married? | ${age} > 18 |
35+
| survey |
36+
37+
In the example above, `${age}` is the reference question, and the answer to `${age}` must be greater than 18 for the “Are you married?” question to be displayed.
38+
39+
### Formatting skip logic conditions
40+
41+
The format of the skip logic condition will differ according to the **type** of the reference question, as detailed in the table below.
42+
43+
| Reference question type | Skip logic condition | Example |
44+
|:-------------------------|:--------------------|:---------|
45+
| select_one | `${reference_question} = 'choice_name'` | `${consent} = 'yes'` |
46+
| select_multiple | `selected(${reference_question}, 'choice_name')` | `selected(${reasons}, 'other')` |
47+
| integer | `${reference_question}` followed by a logical operator (>, <, =) and a number (or a reference to another question) | `${age} >= 18` |
48+
| date | `${reference_question}` followed by a logical operator (>, <, =) and `date('YYYY-MM-DD')` | `${dob} >= date('1975-01-01')` |
49+
50+
<p class="note">
51+
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>.
52+
</p>
53+
54+
## Combining multiple skip logic conditions
55+
56+
Multiple relevance conditions can be combined into a single expression to determine when a question is displayed based on a previous response. Conditions can be combined using **and**, **or**, and **not** logical operators:
57+
58+
- Use **and** when all conditions must be met for a question to be displayed.
59+
- For example: <code>${age} > 18 <strong>and</strong> ${student} = ‘no’</code>
60+
- Use **or** when at least one condition must be met for a question to be displayed.
61+
- For example: <code>${age} < 18 <strong>or</strong> ${student} = ‘yes’</code>
62+
- 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 question to be displayed).
63+
- For example: <code><strong>not</strong>(${age} > 18 <strong>and</strong> ${student} = ‘yes’)</code>
64+
65+
**survey worksheet**
66+
67+
| type | name | label | relevant |
68+
|:--------------|:----------|:-------------------|:----------------------------------|
69+
| integer | age | What is your age? | |
70+
| select_one yn | employed | Are you employed? | ${age} >= 16 <strong>and</strong> ${age} <= 75 |
71+
| survey |
72+
73+
## Adding skip logic based on whether a question was answered
74+
75+
In addition to adding skip logic based on a specific response, you can add skip logic based on whether a question was answered or left blank. This can be useful to add follow-up questions, or when using [acknowledge questions](https://support.kobotoolbox.org/acknowledge.html) in your form.
76+
77+
Unanswered questions are treated as empty strings, noted as two single apostrophes (‘’). The following skip logic conditions can be used:
78+
79+
| Skip logic condition | Description |
80+
|:---------------------|:-------------|
81+
| `${reference_question} != ''` | Display only if `reference_question` is answered (not blank). |
82+
| `${reference_question} = ''` | Display only if `reference_question` is unanswered (blank). |
83+
84+
**survey worksheet**
85+
86+
| type | name | label | relevant |
87+
|:--------------|:-----------|:---------------------|:---------------------|
88+
| text | why_joined | Why did you join? | |
89+
| select_one yn | benefits | Are you seeing benefits? | ${why_joined} != '' |
90+
| survey |
91+
92+
## Adding skip logic conditions to question groups
93+
94+
Skip logic can be applied to question groups as well as individual questions. Applying skip logic to a group will show or hide all questions within that group based on previous responses.
95+
96+
To add skip logic to question groups:
97+
1. Add a **relevant** column to the `survey` worksheet.
98+
2. In the **begin_group** row of the question group you wish to display or hide, enter the condition that must be met **for the group to be displayed.**
99+
100+
**survey worksheet**
101+
102+
| type | name | label | relevant |
103+
|:-------------|:------------|:---------------------------------------------|:-------------------|
104+
| select_one yn | joined | Did you join the association? | |
105+
| begin_group | association | Association participation | ${joined} = 'yes' |
106+
| date | date_joined | When did you join the association? | |
107+
| select_one yn | voted | Have you ever voted in any election for the association? | |
108+
| end_group | | | |
109+
| survey |
110+

0 commit comments

Comments
 (0)