This article is part 2 of our series on repeat groups. See the bottom of this article for the other parts in this series.
This article has several sample forms. For help deploying them to your server so you can follow along, check out our support article Deploying form definitions.
One of the many great features of SurveyCTO is field references, where you can display and use the value of one field in another field using dollar-sign-curly-braces like ${this}
.
For most fields, this is easy, but with a repeat group, how does the form know which repeat instance to use? Does it use the first instance of a repeated field, the second, the last? Should it check multiple values? Luckily, SurveyCTO has lots of great tools you can use to reference repeated fields.
This support article explains in words how to reference repeated data, but perhaps the best way to learn is to simply check out the sample forms linked here, and see how they work.
For some quick answers on performing common functions with repeat groups, you can also skip to the cookbook in part 4.
Table of Contents |
1. In the same repeat group
If you are working in a repeat group, and you would like to use the value of a field within the same repeat group, you can use a simple field reference, with no extra frills.
Example
Check out this sample form. In the repeat group, there is a field called "hh_age", which has this label:
How old is ${hh_name} in years?
The field "hh_age" has a field reference to the field "hh_name", which is also a repeated field. Since it is in the same repeat group, a simple field reference can be used, and it will use the value of that field in the current repeat instance. For example, the first instance of "hh_age" will use the first instance of "hh_name", the value of the second instance of "hh_age" will use the value of the second instance of the field "hh_name", and so on.
Since "hh_name" is in the same repeat group as "hh_age", a simple field reference will work well.
Keep in mind that this will only work if the fields are in the same repeat group. If the fields are in different repeat groups, even if the repeat groups have the same repeat_count, then that field reference will also require a function for working with repeated data. Later, we will discuss how to set this up.
2. Outside of the repeat group
This section is accompanied by this sample form. For convenience, the fields "crop_rev" and "crop_profitable" have calculated default values so you don't have to enter them, but you are welcome to use your own values instead.
If you would like to retrieve the value of a repeated field outside of its repeat group, you will need to use a function that can use repeated data. You can see a full list in our documentation Using expressions, section Working with repeated data.
When choosing a function to use, consider whether you will need to check MULTIPLE instances of a repeated field, or a SPECIFIC instance of a repeated field. For example, do you have a relevance expression that needs to check the sum of all values, or do you just need to check the last value entered? Once you know how you want to reference the repeated field, look through the list of functions for repeated fields, and use the function that suits your needs.
2.1 Using and referencing MULTIPLE values of a repeated field
Most of the functions used for repeated data check every relevant instance of the repeated field, and returns a value based on every repeated value.
We won't go over every function, but let's highlight a few:
2.1.1 Example 1: Adding up all values
Demonstrated in the field "sum" in the sample form on row 26.
Let's say you are doing a farm survey, and your form has a repeated field called "crop_rev" that asks for the revenue from each crop grown. Then, you want to know the total revenue of all crops. To get the total revenue, you can simply include a calculate field with a calculation that uses the sum() function, like this:
sum(${crop_rev})
The sum() function takes a repeated field as a parameter, checks every value of that field, adds them up, and returns the sum. That way, you have all crop revenue, not just the revenue from individual crops.
2.1.2 Example 2: Display list of all values
Demonstrated in the field "join" in the sample form on row 22.
Let's say you want a comma-space-separated list of all crops grown to display in your form. You can use the join() function on the repeated field that stores the crop name, like this:
join(', ', ${crop_name})
Here, the first parameter is the separator, and the second parameter is the repeated field that will be joined.
2.1.3 Example 3: Display list of values that meet a condition
Demonstrated in the field "join-if" in the sample form on row 23.
Let's say you want a comma-space-separated list of all crops grown that are profitable. If the repeat group has a field that determines if the crop is profitable, you can use the join-if() function, where the third parameter is a conditional statement, saying the repeated value in the second parameter should only be included in the list if that crop is profitable:
join-if(', ', ${crop_name}, selected(${crop_profitable}, '1'))
For example, let's say the field "crop_name" is repeated four times, so the enumerator enters these values:
- Apples
- Broccoli
- Carrots
- Dates
Let's say that same repeat group has a field "crop_profitable" that has a value of 1 if the crop is profitable, and 0 if it is not. When filling out the form, the enumerator indicates that Apples, Broccoli, and Dates are profitable, but Carrots are not. In this case, the join-if() expression above would return this value:
Apples, Broccoli, Dates
Notice how "Carrots" is not included in the list, since it does not meet the condition that choice 1 was selected for the field "crop_profitable".
2.2 Using and referencing a SINGLE value of a repeated field with indexed-repeat()
Demonstrated in the fields "rank_name" and "rank_rev" on rows 37-38 of the sample form.
Most functions for repeated data check all values of a repeated field, but what if you need a specific value from a specific repeat instance? In that case, use the indexed-repeat() function.
2.2.1 Indexed-repeat() basics
The indexed-repeat() function can retrieve the value of a specific instance of a repeated field. It uses this structure:
indexed-repeat(repeatedfield, repeatgroup, index)
The function takes three parameters:
- repeatedfield: The repeated field you would like to retrieve a value from. You would like one of the values of that repeated field.
- repeatgroup: The repeat group the field is inside.
- index: Which repeat instance of the repeated field you want.
For example, let's say you have a form with a repeat group called "crop_rep". In that repeat group, the field "crop_rev" asks for the revenue of each crop.
Let's say, outside of the repeat group, you want the revenue of the FIRST crop entered. You can use this expression to retrieve that value:
indexed-repeat(${crop_rev}, ${crop_rep}, 1)
Here, the third parameter has a value of 1, so it will retrieve the value of the FIRST instance of "crop_rev".
If you wanted the value of the SECOND instance of "crop_rev", you would use this expression:
indexed-repeat(${crop_rev}, ${crop_rep}, 2)
And so on like that.
2.2.2 Dynamic indexed-repeat()
The third parameter in an indexed-repeat() expression, the index, is usually a field reference, so it is dynamic. That way, it retrieves a different repeat instance based on its immediate needs.
For example, in the sample form, in the repeat group "crops_again", we want it to retrieve values from the repeat group "crops_rep". Since those two repeat groups have the same repeat_count, "crops_again" can use its own repeat index using the index() function to retrieve the respective values from the "crop_rep" repeat group.
First, we need the repeat index, so the calculate field "again_index" on row 35 has this simple expression:
index()
We can use that in an indexed-repeat() expression. For example, the field "rank_rev" has this calculation:
indexed-repeat(${crop_rev}, ${crop_rep}, ${again_index})
That way, in each new repeat instance of "rank_rev", it will retrieve the value from a different instance of the field "crop_rev". When "again_index" has a value of 1 in repeat instance 1, it will retrieve the first value of the field "crop_rev" from "crop_rep"; when "again_index" has a value of 2 in repeat instance 2, it will retrieve the second value of the field "crop_rev" from "crop_rep"; and so on.
Of course, the best way to learn anything is to try it for yourself, so deploy that form to your server, and try filling it out!
3. Indexed-repeat() errors
When you reference a repeated field outside of its repeat group, but you don't use a special function, you will get an indexed-repeat() error during testing. For help diagnosing these errors, check out our support article Diagnosing indexed-repeat() errors.
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