Differences

This shows you the differences between two versions of the page.

--- en:create:functions:looppage [26.08.2020 22:23] – [loopPage()] sophia.schauer
+++ en:create:functions:looppage [05.09.2023 23:00] (current) – swissel.uni-mannheim
@@ Line 1: / Line 1: @@
 ====== loopPage() ======
-''int **loopPage**(int //startValue//, int //endValue//, [int //increment//])''
+''int **loopPage**(int //startValue//, int //endValue//, [int //Increment//])''
-''int **loopPage**(int //repetitions//)''
+''int **loopPage**(int //Repetitions//)''
-''mixed **loopPage**(array //elements/)''
+''mixed **loopPage**(array //Elements//)''
-Repeats the page -- beginning with the //start value// -- in a loop as often as it takes until the //end value// is reached. The current value is returned each time.
+Repeats the page -- starting with the //startValue// -- in a loop until the //endValue// is reached. The current value is returned in each case.
-  * //startValue//\\ value on the first pass
+  * //startValue//\\ The value at the first pass.
-  * //endValue//\\ value on the last pass
+  * //endValue//\\ The value at the last pass
-  * //increment//\\ (optional) change in value on every loop pass (standard: 1) -- you can create an endless loop with the //increment// 0, which can be terminated using ''setNextPage('next')''.
+  * //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 nummeric parameter (//repetitions//) is specified the page will repeat as often as determined. The counter variable begins with 0 in this instance.
+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.
-  * //repetitions//\\ number of repetitions
+  * //repeats//\\ number of repetitions
-**Note:** To repeat more than one page, please use ''[[looptopage|loopToPage()]]''.
+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.
-===== Example =====
+  * //elements//\\ Elements to loop through.
-<code php>// PHP code on the first page in the questionnaire
+**Note:** To repeat multiple pages, use ''[[looptopage]]''.
-// create, shuffle and cache list with questions
+**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',
@@ Line 29: / Line 53: @@
 );
 shuffle($questions);
-registerVariable('questions');</code>
+registerVariable($questions);</code>
-<code php>// PHP code later in questionnaire
+<code php>// PHP code later in the questionnaire
 $i = loopPage(6);  // 6 repetitions - equivalent to loopPage(0,5)
 question($questions[$i]);
 </code>
-**Note:** As the same page is shown repeatedly, the response times for all repetitions are added up. You have to use multiple pages instead of ''loopPage()'' if you want to collect the processing times separately.
+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.
-<code php>// PHP code later in questionnaire - page 21
+==== 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]);
@@ Line 44: / Line 81: @@
 question($questions[1]);
-// and so on.
+// 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.