This article is part 1 of our series on repeat groups. See the bottom of this article for the other parts in this series.
Sometimes, you may want to ask the same question more than once. For example, in a household survey, you may have fields that ask about the respondent's name and age, and you want to ask those questions for each household member. You could add the same fields multiple times, but this can be time-consuming, and it makes the form less efficient. To display a field more than once, you can simply put it into a repeat group.
In this guide, we will go into detail on how to work with repeated data, including how to create basic repeat groups, reference repeated data, and diagnose issues with repeat groups. If you are already familiar with repeat groups, feel free to skip ahead to the section that applies to you.
| Table of Contents |
For help deploying the sample forms in this support article to try them out, check out our support article Deploying sample forms.
1. Adding a repeat group
To make a field appear more than once, simply put it into a repeat group. Here is how to add a repeat group.
1.1 In the online form designer
Start by clicking a plus on the left where you would like to add the repeat group.
In the module that opens:
- Go to the Add a group tab
- Give the group a label.
- To make the group a repeat group, under Repeat the questions in this group, select Yes.
- Click Configure, and the group editor will open.
(Process continues below)
We'll talk about a few of the other group properties later, but for now, all you have to do is give the group a name. Once the repeat group has a name, click Save now, and the repeat group will be created!
Now, whenever you would like a field to appear more than once, simply add it to that repeat group. All fields in that repeat group will repeat the same number of times.
If you would like a different field to repeat a different number of times, you can add it to a separate repeat group. If you would like a field to be hidden in certain repeat instances, you can give it a relevance expression.
1.2 Using a spreadsheet form definition
To learn how to add a repeat group in a spreadsheet, check out part 2 of our support article Working with spreadsheet form definitions, section 3. Adding groups.
2. Determining the number of repeat instances
A repeat group will repeat multiple times. A single instance of a repeat group is called a repeat instance. The number of repeat instances in a repeat group is called a repeat count. A repeat instance can either be added manually, or the repeat count can be calculated automatically.
2.1 Manually adding repeat instances
By default, repeat instances are added manually by the enumerator. When they reach the repeat group, they will be prompted if they would like to add a new repeat group instance.
When they get to the end of the repeat group instance, they will be prompted to add another repeat instance.
This will keep going until the enumerator taps DO NOT ADD.
To remove a repeat instance, tap-and-hold the field label, then tap Remove group.
2.2 Automatic repeat count
Manual repeat counts can work well for more basic forms, but generally speaking, it is better to determine the repeat count automatically, so there is less work for the enumerator.
Repeat groups have a property called repeat_count. This can be found in the group editor in the online form designer, and it is also a column in the spreadsheet form definition.
The repeat_count property in the online form designer
The repeat_count can either be a simple number, a field reference, or an expression.
2.2.1 Static repeat count (Set count to a specific fixed value)
This is demonstrated in this sample form.
To have a repeat group repeat the same number of times no matter who is filling out the form, have the repeat_count simply be a number.
For example, let's say you are doing a farm study, and you want to ask each farm about the same four crops: apples, bananas, carrots, and dates, and you want to ask the same questions for each crop. Since the fields for each crop will always be the same, you can ask your questions in a repeat group with a repeat_count of simply 4.
2.2.2 Field reference repeat count (Set count to previous response or field)
This is demonstrated in this sample form.
Perhaps the most common repeat count is a simple field reference.
For example, let's say you are doing a household study, where you will not know the number of household members until the enumerator is on site. You can add an integer field that asks how many household members there are, and then have a repeat group with a repeat_count based on that integer field. That way, it repeats once for each household member, and the enumerator can ask the same questions each time.
Further reading: Why a repeat_count value doesn't revise down
2.2.3 Expression repeat count (Set count based on an expression)
This is demonstrated in this sample form.
The repeat_count can also be an expression.
For example, let's say you have a repeat group called "roster_rep" that collects a roster of household members, where repeat instances are added manually. Then later, you want to cycle through that same roster of household members. Instead of having to re-add those repeat instances again, you can simply use the count() function in the repeat_count, so the new repeat group repeats the same number of times as the last repeat group.
This is a very simple example, but expressions can get infinitely complex. You can learn more in our documentation Using expressions.
Tip: Often, it is better to have the repeat count expression be a calculation in a calculate field, and then use a field reference to that calculate field for the repeat_count. That way, if there is an issue, troubleshooting is a lot easier.
3. The index() function
To keep track of which repeat instance you are on, use the index() function. The index() function retrieves the current repeat instance number. In repeat instance 1, it has a value of 1; in repeat instance 2, it has a value of 2; and so on. In the sample form, the field "hh_index" is a calculate field with this simple calculation:
index()
Then the field "hh_name" has this label:
What is the name of household member ${hh_index}?
That way, the field label can display which repeat instance the enumerator is on, and help them keep track of their progress.
The index() function can also be helpful for retrieving choice labels, pre-loading, and more.
3.1 Tip for advanced users
While you can use the index() function multiple times in different expressions in the same repeat group, it is generally better to have a calculate field with that calculation, and then reference that calculate field. This will improve form performance. This does not matter as much for shorter forms, but it can help improve longer forms on less-powerful devices.
For example, instead of this:
| type | name | calculation |
| begin repeat | rep_1 | |
| calculate | choice_value | selected-at(${field1}, index() - 1) |
| calculate | get_hh_name | selected-at(${field2}, index() - 1) |
| end repeat | rep_1 |
Do this:
| type | name | calculation |
| begin repeat | rep_1 | |
| calculate | index1 | index() |
| calculate | choice_value | selected-at(${field1}, ${index1} - 1) |
| calculate | get_hh_name | selected-at(${field2}, ${index1}) |
| end repeat | rep_1 |
In the second example repeat group, notice how the index() function is only used once, and the other fields instead reference the field that uses the index() function.
More on repeat groups
- Repeat group basics: What repeat groups are, and how to use them.
- Using and referencing repeated data: How to use repeated data in other parts of your form.
- Nested repeat groups (advanced): How to use a repeat group inside of a repeat group.
- Cookbook: Various tools and examples of using repeat groups and functions you can use in your own forms to retrieve and generate the data you need.
Do you have thoughts on this support article? We'd love to hear them! Feel free to fill out this feedback form.
0 Comments