====== loopPage() ======

''int **loopPage**(int //startValue//, int //endValue//, [int //Increment//])''

''int **loopPage**(int //Repetitions//)''

''mixed **loopPage**(array //Elements//)''

Repeats the page -- starting with the //startValue// -- in a loop until the //endValue// is reached. The current value is returned in each case.

  * //startValue//\\ The value at the first pass.
  * //endValue//\\ The value at the last pass
  * //Increment//\\ (optional) Change the value on each loop pass (default: 1) -- with the //Increment// 0 you can create an infinite loop which can be terminated with ''setNextPage('next')''.

If only a numeric parameter (//repeats//) is specified, the page will be repeated as many times as specified. The count variable starts with 0 in this case.

  * //repeats//\\ number of repetitions


If only one array is specified as parameter (//elements//), the page will be displayed once for each element of the array and the function ''loopPage()'' will return the element of the array each time.

  * //elements//\\ Elements to loop through.

**Note:** To repeat multiple pages, use ''[[looptopage]]''.

**Note:** For sample code to use, see the instructions for ''[[looptopage]]''.

===== Application examples =====

==== All questions of a rubric in random order ====

<code php>
if (!isset($questions)) {
  // List of all questions from section RS
  $questions = getQuestions('RS');
  // Shuffle and cache the list of questions (array)
  shuffle($questions);
  registerVariable($questions);
}
// Process all identifiers from the $questions list
$questions = loopPage($questions);
question($questions);
</code>


==== Present questions in random order II ====

<code php>// PHP-Code auf einer der ersten Seiten im Fragebogen
// Create, shuffle and cache list of questions
$questions = array(
  'AB01', 'AB02', 'AB03',
  'AB04', 'AB05', 'AB06'
);
shuffle($questions);
registerVariable($questions);</code>

<code php>// PHP code later in the questionnaire
$i = loopPage(6);  // 6 repetitions - equivalent to loopPage(0,5)
question($questions[$i]);
</code>

In this example, the list of questions is already defined and shuffled earlier in the questionnaire. This eliminates the IF construction with ''isset()'', which prevents the list from being shuffled again in the above example.

==== Questions in random order with dwell time ====

**Note:** Because the same page is displayed again and again, the response times for all repetitions are added. If you want to collect the processing times separately, you have to use multiple pages instead of ''loopPage()''.

<code php>// PHP code on one of the first pages in the questionnaire.
// Create, shuffle and cache list of questions
$questions = array(
  'AB01', 'AB02', 'AB03',
  'AB04', 'AB05', 'AB06'
);
shuffle($questions);
registerVariable($questions);</code>

<code php>// PHP code later in the questionnaire - page 21
question($questions[0]);

// PHP code on page 22
question($questions[1]);

// etc.

// PHP code on page 26
question($questions[5]);
</code>


===== Workaround for page sequence =====

Within a page order defined by ''setPageOrder()'', ''loopPage()'' cannot be used. This would break the page sequence.

If you want to repeat a page within a page sequence, then define this repetition already in the page sequence. In the following example, for example, the page with the identifier "loop" is repeated four times:

<code php>
setPageOrder(['a1', 'a2', 'a3', 'loop', 'loop', 'loop', 'loop', 'b3', 'b2']);
</code>

To determine which repeat the page is currently in, you can use the function ''loopIndex()''. This shows at which point of the page sequence you are currently, starting to count with 0. So on the page "loop" it would get the value 3, 4, 5 and 6.

Here you could simply subtract 3. But if the repetition appears in a different place in the questionnaire, you can work using ''registerVariable()''. The following code on the "loop" page would use ''$i'' to return the value 0 to 3, no matter where the page is repeated.

<code php>
// Determine the current position
$pos = loopIndex();
// Check if we already know the first position of this page
if (!isset($firstIndex)) {
  $firstIndex = $pos;
  registerVariable($firstIndex);
}
// Store the different in variable $i
// this corresponds in other codes to $i = loopPage(...)
$i = $pos - $firstIndex;
</code>

If you repeat several (different) pages, you must use a different variable name instead of ''$firstIndex'' in each case.