How To Set The Order Of Iterations Within a Loop

Overview

By default, SurveyToGo executes loop iterations in their natural order (1, 2, 3, and so on). In some scenarios, however, you may want to control the order in which iterations are displayed.

SurveyToGo provides a callback function that allows you to define a custom iteration order for a loop chapter at runtime.

Step 1: Add the Callback Function

Open the survey's Advanced Scripts section and add the following callback function:

function OnCreateIterationOrder(inChapterIndex, inIterationOrder)
{

}

Understanding the Callback

The OnCreateIterationOrder() function is called automatically by the SurveyToGo runtime whenever a loop chapter is entered during an interview.

Parameters

inChapterIndex

The index of the loop chapter currently being executed.

This allows you to identify which loop is requesting a custom iteration order.

For example, if your survey contains multiple loop chapters, you can use this parameter to apply different iteration logic to each loop.

inIterationOrder

An array containing the iteration order that will be used by the loop.

You can modify this array to define your own custom sequence of iterations before the loop begins.

Example 1

A common approach is to check the chapter index and then modify the iteration order only for a specific loop chapter:

function OnCreateIterationOrder(inChapterIndex, inIterationOrder)
{
    if (inChapterIndex == 10)
    {
        // Custom iteration order logic
    }
}

In this example, the custom logic is applied only when loop chapter 10 is entered.

 

Note: The index is 4 in this case.

And the 2^nd parameter, ‘inIterationOrder’ passes through the original iteration order of the loop.

Example:
If chapter 1 is a loop that iterates 5 times, it will pass through: [1,2,3,4,5].

Add the relevant code to the Call-Back function in order to perform your logical script.

Configure your function to suit your logical scripts.
In the above example (screenshot) chapter 4 (Q11) iterates 5 times based on an answer scale.

Example 2: Using the Same Order as a Randomized Question

Suppose you have a question with the variable name Q1 that contains five answers and has been configured to randomize its answer order.

If you want a loop chapter to iterate in the exact same order that the answers of Q1 were displayed, you can use the GetQuestionAnswersRandomOrder() function inside the OnCreateIterationOrder() callback.

Add the following code inside the callback function created in Step 1:

function OnCreateIterationOrder(inChapterIndex, inIterationOrder)
{
    var randomOrder = GetQuestionAnswersRandomOrder(Q1);

    for (var i = 0; i < randomOrder.length; i++)
    {
        inIterationOrder[i] = randomOrder[i];
    }
}

How It Works

1. GetQuestionAnswersRandomOrder(Q1) retrieves the randomized answer order that was generated for question Q1 during the interview.

2. The returned array contains the answer indexes in the order they were displayed to the respondent.

3. The callback copies this order into inIterationOrder.

   1. 

4. The loop chapter will then execute its iterations in the same sequence as the randomized answers of Q1.

Common Use Case

This technique is useful when:

• A respondent evaluates a randomized list of brands, products, or attributes in Q1.

• A subsequent loop chapter asks follow-up questions about those same items.

• You want the follow-up questions to appear in the exact same order as the original randomized list.

Using the same randomized order helps maintain consistency throughout the interview and improves the respondent experience.

You can write any script that you wish in order set different loop iterations order with this method.

Common Use Cases for Loops

Custom iteration ordering can be used for:

• Randomizing loop iterations.

• Displaying iterations in a predefined sequence.

• Prioritizing selected items.

• Implementing advanced respondent-specific ordering logic.

• Synchronizing iteration order across multiple loop chapters.

The OnCreateIterationOrder() callback provides full control over the sequence in which loop iterations are presented during the interview.

Tip:

As Chapter indexes may move while you script (add additional chapters etc.) you can build a function that returns the chapter index from its name.