Programming Iterations/Loops

Overview

Loops are very helpful when programming surveys. Loops enable you to write a set of questions once and then display this set of questions for any number of times without having to “copy & paste” these questions. Loops are implemented in SurveyToGo as a property of a chapter. This means that once you configure the chapter to loop, all the questions inside this chapter will be displayed according to the loop settings.

How to make it happen

Configuring loops is very easy. Simply follow these steps:

1. Add the questions you would like to loop, and make sure to put them under a chapter.
2. Configure the loop options of the chapter.

Below you will find 2 examples of common looping scenarios and how to configure them:

1. Example 1: Looping for X number of times according to a numeric question
2. Example 2: Looping for X number of times according to a multi select question

Step 1: Add the questions you would like to loop

The first thing to do when working with loops is to add a chapter and then add all the questions you wish to include in the loop under that chapter. To add a chapter, either right click the Root Chapter and select “Add sub-chapter”:

Or select the “Add chapter” from the toolbar menu:

Then follow the regular procedure to add questions under that chapter. Please refer to earlier chapters in this manual to learn more about adding questions and chapters.

Step 2: Configure the loop options of the chapter

Once all the questions are in place, click on the chapter that contains them and select the “Loops” tab:

The loop tab contains the following iteration options:

Option	Description
No Iterations	Do not loop this chapter
Iteration Maximum number of times	Loop this chapter based on a maximum number of times
Iterate By scale	Loop this chapter through the items present in a pre-configured scale – see Chapter 12 for scale reference
Include in Chapter Locator	Include all the loops of this chapter in the chapter locator if the chapter locator is enabled.
Randomize Iterations	Loop this chapter each time using a different order. Specifically useful when used with scales.
Print only one	When printing the survey using the “Survey > Print” action, print only the first iteration.

The tab also contains the following code sections:

Section	Description
Iteration Break Rule	If this expression is true, the loop will end.
Iteration Start Script	This script will be run at the start of each iteration of the loop.
Iteration End script	This script will be run at the end of each iteration of the loop.
Iteration Entrance Rule	If the entrance rule evaluates to false, the specific iteration will be skipped.

Example 1: Looping for X number of times according to a numeric question

Let’s suppose we need to ask a certain set of questions for each room in an apartment. In this case we will first ask how many rooms there are in the apartment, and then loop through the per-room questions for the number of times necessary.

To perform this example we will do the following:

1. Add the numeric “how many rooms” question + add the chapter with the “per-room” questions.
2. Configure the looping.

Step 1: Add the numeric “how many rooms” question.

Step 2: Configure the looping

We will assume there are a maximum of 8 rooms in the apartment and will there for set the “Maximum Iterations” to 8:

We will then configure the break rule to stop the rule when we hit the number of rooms that was specified in Q1:

Note the use of the new “IterationIndex” value that specifies the current iteration number. The code above checks the answer to Q1 and when the current loop reaches that number, the loop will break.

You can now run the survey and see how it works.

Example 2: Looping for X number of times according to a multi select question

Let’s suppose we need to ask a certain set of questions for each brand that the respondent has recognized. In this case we will first ask which brands the respondent recognizes, and then loop the “per-brand” questions only through the brands that were specified.

To perform this example we will do the following:

1. Add the multi select “Which brands do you recognize” question + add the chapter with the “per-brand” questions.
2. Configure an answer scale for easier looping configuration.
3. Configure the looping.
4. Show the brand name in the first question.

 

Step 1: Add the numeric questions

Step 2: Configure an answer scale for easier looping configuration

To quickly create a scale out of a question answers, you can right click on the question and select the “Make into scale” option:

You will now be able to reuse this scale throughout the survey and also in the Loops tab as you will see below. Please refer to Chapter 12 for more information about scales.

Step 3: Configure the looping

We will use the newly created scale when configuring the looping parameters:

This instructs the survey to loop through the available brands in the list of brands we have configured. We will now add an entrance rule to make sure the survey skips the brands which were NOT selected in Q1. First, select the “Use entrance rule” option:

Then add the following entrance rule. Make sure you are adding the code to the Iteration Entrance Rule section:

Since the chapter loops through the scale that is also used with Q1, this rule checks if the user has selected in Q1 the current iteration item.

You can now run the survey and see how it works.

 

Step 4: Show the brand name in the first question

You can make use of the newly introduced “IterationName” value to show the name of the brand anywhere you need to. Let’s configure the first question of the loop chapter to show the current brand name for which we will ask questions.

Below is the text of the empty question that will hold the brand name. Notice the {0} at the end that is used for text substitution:

Now, let’s add a start script to this question that will replace the {0} with the current brand name:

Notice the use of the “IterationName” value to specify the current iteration name. Please note that since we are iterating through a predefined scale, the IterationName equals the name of the answer from the scale which in our case is the brand name.

 

Exporting iteration data:

Exported iteration names depends on the type of the loop chapter

1. Loop chapters that are iterating by a scale:

The name for each question inside the loop chapter will start with the name of the answer in the scale and then the name of the question as it is defined to be exported.

Example: If the loop is iterating by a scale which has an answer called "Brand 1" and inside the loop chapter I have a single choice question with a variable name: Q_1 then the exported iteration data for this question will have this name: Brand 1_Q_1

2. Loop chapters that are iterating a maximum amount of times: 

The column name for each question inside the loop chapter will start with the iteration index - "I_NumOfIteration" and then the name of the question as it is defined to be exported.

Example: If the loop is iterating a maximum of two iteration and inside the loop chapter I have a single choice question with a variable name: Q_1 then the exported iteration data for this question will have these two names: I_1_Q_1 and I_2_Q_1

 

Note: you can choose to export the iterations with their coding format, to have the codes of the scale's items (if running by max iterations, the codes would be the same as the iterations indexes), by enabling the 'Use Coding Format For Iteration Export' in the survey properties: