Understanding indexed-repeat() and the structure of repeat-group data

One of the most common support requests we get is from users who get an error message that tells them to use indexed-repeat(), because they are not sure what that means.

indexed-repeat() is a function you might need to use when you refer to a field that is inside a repeat group

Referring to a field's value

Normally, when you reference a field in another part of the form – in a constraint, relevance, or calculation expression, for example – you can refer to the field directly by enclosing it in "${}" (e.g. "${age}", to return the value stored  in "age"). For example, in this form excerpt I have referred to the "age" field in the relevance condition for the "schooling" field:

[Note: The above image is from a form definition in Excel. SurveyCTO also has an online drag-and-drop form designer, but here it's easier to see multiple fields and selected properties in the raw form definition.]

Iterations of repeated fields

However, if you are referring to a field that is inside a repeat group from outside that repeat group, you will not be able to refer to that field using a simple ${fieldname} reference. The reason is that a field inside a repeat group does not exist only once. Rather, there are multiple copies of that field, one for each instance or iteration of the repeat group. 

For example, let's say that you had a household roster implemented as a repeat group, with an "age" field inside it because you want to know the age of each household member. And let's just say that you set that repeat group to repeat 10 times. Here's how that might look in the form definition:

During the survey, because the repeat group will repeat 10 times, there will not just be one "age" field. There will be ten fields called age, each with a different value (the different ages of the different household members). One way to imagine how these fields are stored in the survey is to think of an array with the index number next to the field name that indicates each copy of the field:

Referring to a repeated field's value

If you refer to ${age} inside the same repeat group, then SurveyCTO assumes you want the current "age" value from the same repeat instance. But if at a later point in your form, from outside the household roster repeat group, you referred to ${age}, how would SurveyCTO know which of the 10 "age" values you want? It can't, which is why you will get an error that suggests you use the indexed-repeat() function. Using indexed-repeat(), you will  provide instructions on which instance of the field in question you want.

In order to refer to the correct instance of the field, you need to tell SurveyCTO three things:

  1. The field you want (in this case ${age}).
  2. The repeat group that the field is inside (in this case ${hhroster}).
  3. The index number of the field (that is, the number that indicates which copy of the field you want). The index always corresponds to the instance of the repeat group in which the field was asked. For example, the age field in the first loop of the repeat group has an index of 1, the age field asked in the second loop of the repeat group has an index of 2, and so on.

How do you tell SurveyCTO each of these three properties of the field? You use the indexed-repeat() function, which has the following syntax:

indexed-repeat(${fieldname}, ${repeatgroupname}, index_number)

For example, in the below form excerpt I use a calculate field to return the response from the fifth instance of the "age" field and then display the result in a note field:

As you can see, in order to refer to the "age" field from outside the repeat group, I first have to enclose it in an indexed-repeat() function that specifies the exact copy of the age field I am referring to. 

Learn more about indexed-repeat()

I hope you found this helpful! If you are getting an indexed-repeat() error message and want to specifically understand how to diagnose the error and which exact field in your form is causing the error, you can read this help topic which breaks down the typical indexed-repeat() message in detail.

You can also find more detail about the syntax for the indexed-repeat() function, including how to use it in more advanced cases (such as when you need to refer to a repeated field that is within multiple repeats, or need to refer to a repeated field from inside another repeat group) by reading about the indexed-repeat() function in this help topic on all the different functions you can use in SurveyCTO.

We also have several sample forms themed around the use of repeat groups for rosters. Please see these too to broaden your understanding of repeat groups and indexed-repeat().

Do you have thoughts on this support article? We'd love to hear them! Feel free to fill out this feedback form.


Article is closed for comments.