Table of Contents:

Overview

There are scenarios in which we may need to loop through a set of questions until a certain condition is met. For example, during the registration of a parent we may need to iterate over their children to capture their information too. In programming, this is achieved by an element called loop, in CommCare, these are known as Repeat groups. Considering that the logic to stop a repeat group can be dependent on many factors, CommCare provides 3 types of repeat groups, namely: User Controlled, Fixed number and Model Iteration. The image below exemplifies how a repeat group should be visualized.

Open

 

n can be:

• User controlled (the user chooses to repeat)

• Fixed number (a constant or a value defined by the user)

• Model Iteration (based on a set of elements such as cases, items of a lookup table items, etc)

Common characteristics of repeat groups

Before going any further, it’s important to understand a few concepts related to repeat groups

• Each loop is usually called a repeat or an iteration

• Repeat group iterations are indexed and start at 0

  • There is an exception to this rule, when referencing a specific iteration of the repeat group the count starts at 1 (find more about this below)

• Repeat groups can be used in case management to create child cases

• Repeats or iterations cannot be removed 

Types of Repeat groups

User controlled

At its basic setup, i.e. without any settings defined, a repeat group will prompt the user asking if they would like to add an iteration and only stop when the user replies “No”, hence the name User controlled repeat group. For example, a laboratory technician capturing patient demographics and respective diagnosis from a batch of test results, they can enter as many as needed.

Open

Testing User Controlled Repeat Groups with Live App Preview:

If you observe unexpected behavior on a very simple user-controlled where none of the questions in the repeat are showing in the form on app preview, clear the browser data and re-test.

Fixed Number

In this case, the number of iterations is defined before the initiation of the repeat group by the user, a numerical expression or a constant (set by the app builder). To enable this repeat group, click on the question (i.e.  How many children live this household? ) in the Question Tree and drag it over to the repeat count box on the left - when you let go you will see that CommCare has created a blue reference in the box. Numeric values are not supported (in case of a constant, it needs to be put in a hidden value first). 

A scenario when this type of repeat group is particularly useful is during the registration of a parent, before capturing information about its children, it’s common to first ask the number of children.

Model Iteration

There are scenarios in which it is necessary to go over a set of elements of a given data model, hence the name. These elements can be cases, locations, lookup table items, etc, most of the data components found in CommCare apps, as long as they are known when the form is loaded.

To enable this type of repeat group, it’s required to set in the field Model Iteration ID Query an XPath query expression to fetch the elements that are supposed to be looped through. Observe that, Model iteration repeat groups actually go over a collection of values therefore the expression needs to reference a property or attribute of the model, preferable one able to uniquely identify the elements.

Examples of valid XPath query expressions:

• Loop through existing patients:

  • instance(‘casedb’)/casedb/case[@case_type=’patient’]/@case_id

• Loop through provinces defined in the organizational structure (assuming that the fixture of the location hierarchy is flat)

  • instance(‘locations’)/locations/location[@type=’province’]/@id

• Loop through a list of medicines stored in a lookup table called medicine:

  • instance('medicine')/medicine_list/medicine/id

Internal structure

Model iteration repeat groups have a different internal structure compared to other repeat group types. The main differences are:

• Inner folder item -  any content inside the repeat group will actually be inside this folder and when referencing a question from the inside or outside of the repeat group this needs to be considered

• @id attribute - used to store the “id” of the current iteration of the repeat group according to the Model Iteration Query ID expression

• @index attribute - returns the index of the current iteration of the repeat group, starts at 0

Filtering out elements based on form questions

As stated above, the list of elements must be defined when the form gets loaded. In case there is a need to filter out elements based on some question inside the form, the workaround is to add a display condition to an internal folder where the content lives, this will ensure that depending on the answer to the question only a subset of the elements are looped through. Example:  Loop through farmers who grew soya this year.

Calculations with repeat groups questions

Inside the repeat group

• Logic between questions - there 2 ways in which a question can reference other(s) inside the same repeat group:

  • Absolute path: this means referencing questions by their full path. Because the expression is executed inside the repeat group, Commcare knows that it should get the value from the current repeat.

  • Relative path: this options allows referencing a question by navigating the structure of the repeat group. This is achieved by using the function current() and expression “..” (see more below).

• Position function - this function returns the index of the current repeat (numbering starts at 0).  

  • Syntax: position(question) - question needs of a repeat group type

  • Example: Let’s say there is a question, whose ID is some_question, inside a repeat group, called some_repeat_group, executing the expression “position(current()/..)” in some_question would return 0 for the 1st repeat, 1 for the second and so on.

• Parent expression (..) - this expression is used to move one level up, referencing that way the parent of the question where the expression is located. Multiple “..” can be combined if there are many levels within the group.

  • Example: In the previous example, executing the expression “current()/..” in some_question would move the "cursor" to the parent level, some_repeat_group.

• Current function - useful when navigating inside the repeat group to reference the current question. In most expressions, current() is dispensable, however, it’s good practice to include it, makes the expression more easier to interpret. 

  • Example:

    • current()/..                     ->   ..

    • date(current()/../dob)    ->  date(../dob)) 

    • position(current()/../..)   ->  position(../..)

Outside the repeat group

Because a question inside a repeat group will have several responses (one for each iteration), referencing them outside the repeat group needs to take into account that a collection of values will be returned. A few possible ways to work with them are:

• Access a question by index - using square brackets it is possible to access a specific question in a specific iteration (numbering starts at 1).  To refer to a specific loop, the brackets [x] need to be placed after item, rather than after the repeat group name (as in the other repeat groups). Note that this does not work with easy references, only with the text-based /data/child_repeat[1]/name style of references.

  • Example: /data/child_repeat[1]/name will access the name of the first repeated child.  

• Join all values into one - it’s possible to combine the values of a single question into one string using the join function.  

  • Example: join(", ", /data/child_repeat/name) will join together each name, separated by a comma and a space.

• Count function - the count function will return the number of times a particular question was repeated.  

  • Example: count(/data/child_repeat) will give the number of children.  

• Filtering by question answer - it is also possible to filter iterations based on an answer provided in the repeat. This is done by using a filter in square brackets.  

  • Examples: 

    • To count the number of children who are female: count(/data/child_repeat[gender = 'female']).  

    • To get the name of the first female child who is over 3 years old: /data/child_repeat[gender = 'female'][age > 3]/name[0]

Repeat groups and Case management

A special use case involving repeat groups is the ability to create child cases. In order to use this feature, it’s required to setup the Child Cases section with questions from a repeat group, such questions are identified with a dash at the beginning of the question path. Note that questions from inside the repeat group won’t be available to the parent case section.

Reducing the number of repeats

It is currently not possible to physically delete a node within a repeat group once it has been created. This means that, in case something forces the reduction of the number of repeats, the previous (higher) number won’t be affected, which can subsequently lead to ambiguous behavior and errors. 

Fixed number

In a fixed number repeat group, if the user enters an initial value and then changes it to something smaller, so from 5 to 3, 5 repeat nodes will still show up. To prevent this from happening there are a few implementation considerations to consider:

• Add a group question type immediately within the repeat group, and place all of the inner contents of the repeat group inside that inner group. 

• Set the display condition of the inner group as position(..) < repeat_count_question (where repeat_count_question is the full path of the integer question that defines the repeat count)

User Controlled

Here, the number of iterations is not dependent on some question inside the form but by the user action. In this case, because we can’t go back to the question that influences the number of iterations, the workaround is to allow the user to cancel the iteration, eliminating that way awkward behavior around removing the repeat data. To do that follow:

• Add a checkbox question type, or some other type, immediately within the repeat group, indicating an option to cancel the repeat group

• Add a group question type after the checkbox questions and place all of the inner contents of the repeat group inside that group

Advanced Functions for Repeat Groups

Overview

Repeat groups can have multiple questions with the same path (ex. /data/child_repeat/name). For this reason, special functions are required when writing logic within a repeat group. 
The Parent Function: (..)

Using the parent function (..) allows access the parent of the current question. For example, if writing logic for the question "What is Your Name?", typing (..) will access the /data/child_repeat in logic which can then be used to access another question within the same repeat.  

The Position Function: position( )

In a hidden value, the position function (position ()) placed in a calculate condition will return the position of a question in a repeat group (i.e., first, second).  The position function is zero-indexed meaning that numbering starts with zero (0) and continues.

❗Limitation: Using the position function may cause inconsistent behavior with nested elements and conditional usage. This issue can be avoided by using the position function in the default value of a question instead of in the calculate condition. 

The Current Function: current( )

The current function (current( )) will return a relative value to questions inside a repeat group which can be used for any predicate filter that makes use of square brackets [ ].

Model Iteration inside of a Question List

Repeat groups that are inside of a question lists require a fixed repeat count, so a model iteration ID query cannot be used. Therefore, a hidden value outside the question list to store the number of items to iterate is needed along with a hidden value inside the repeat group to store the current position. Also, a question to fetch each item from the models is required.

Below is a form that iterates these items in a question list.

Relevant fields and respective values needed are shown in the table below:

Logic Outside of a Repeat Group

Paths can point to multiple questions so special functions must be used to access specific repeated values.  
 

Access a Question by Count:

Accesses a specific question (ex. Question 2 in a group) using square brackets.

Find the Number of Times a Question is Repeated: (count(question_path)

Returns the number of times a question is repeated.  
 

Filtering by Question Answer

 Accesses a specific question based on an answer provided in a repeat group by using a filter in square brackets.  

Removing Repeat Groups (Mobile)

In applications with user-controlled repeat counts, users can inadvertently create repeat groups that are not needed. Deleting groups can cause errors so mobile applications prevent users from creating repeat groups. If repeat groups are essential, they can be created by placing questions inside of a repeat into a group, and using the group's display condition to eliminate the questions inside of the repeat. This allows the user to be prompted to cancel the creation of a repeat group.

Below is an example of the way this is displayed on CommCareHQ in the Form builder.

Below is a table with question properties.

Note: Fields that are not displayed in the table (I.e., validation condition, repeat count) have been left blank.

Advanced Demo: Model Iterations for item list repeats

Using Item Lists, it is possible to make forms which ask users repeated sets of questions per item in the list. Using "Model Iteration" it is possible to extend this pattern to provide multiple "loops" of questions over an item list, and even reference the user's answers in one set of repeated questions when displaying the next set of questions inside of the form.

Using This Demo

• Download the lookup tables excel file here and import it into your project space's lookup tables list. You should have a resulting lookup table called "iterables".

• Next, download the attached XForm here, and upload that form into your application. 

• Make sure to be logged in as a mobile worker to test the form, you will need to be able to access the lookup table.

Notes

Each repeat group has a pattern where the repeat is split into two portions. The first portion is responsible for loading data from either the lookup table or another repeat group. The second portion contains the questions. In the second portion, all data references are "easy" and don't require use of current() or making "relative steps" (like "/../") to other areas. This is an important best practice to follow to avoid complex issues if elements are moved or re-ordered.

Using a single root "Questions" group inside of a repeat allows the repeat to be "Skipped" without being removed, even though the user experience is the same This is a critical pattern for complex logic with repeats.

The calculations for this pattern require using both "native" XPath references ("/data/path/to/question") rather than "easy" references (#form/question), and also require use of current() and relative steps. It is very helpful to have a test form like this to test changes you want to make in isolation outside of the context of much larger, much more complex forms.

It is possible to reference data from previous "loops" of a repeat in Hidden Value calculations, but it isn't meaningfully possible to do the same with default values, since all of the questions are created upfront, and since the user may change the original question after it is created.