====== setPageOrder() ======

Normally, pages in the questionnaire executed consecutively from the first to the last page provided that ''[[:en:create:functions:setnextpage|setNextPage()]]'' or ''[[:en:create:functions:gotopage|goToPage()]]'' do not interrupt this page order.

The function ''setPageOrder()'' allows a different page order to be selected from the start and this can be used at any given moment in the questionnaire. The new //page order// is set from when the user clicks on "next" (the questionnaire starts with page 1 in each instance).

''void **setPageOrder**(mixed //pageorder//)''

  * //pageorder//\\ One or multiple page IDs that were specified as an array or a comma-separated list. Page ranges can be specified using a hyphen, see examples:

^Page Order^Effect^
|'''pageA, pageB, pageC, pageD'''|shows pages with IDs ''pageA'', ''pageB'', ''pageC'' and ''pageD'' consecutively|
|''array('pageA','pageB','pageC','pageD')''|:::|
|'''pageA-pageD'''|shows all pages from ''pageA'' to ''pageD''|
|'''pageA-pageD, pageE-pageK'''|shows pages from ''pageA'' to ''pageD'' first and then pages from ''pageE'' to ''pageK''|
|''array('pageA-pageD','pageE-pageK')''|:::|
|'''pageA-pageD,pageE,pageC,end'''|shows all pages from ''pageA'' to ''pageD'' first, then the pages ''pageE'' and ''pageC'' one after the other, and then ends the questionnaire with the last page.|

Once the defined page order has been executed, the page that follows in the "normal" order on the last page of the page order will be shown. 

**Note:** The commands ''setNextPage()'', ''loopPage()'' and ''setPageOrder()'' interrupt the page order:

  * The command ''setNextPage()'' interrupts the page order and returns to the "normal" page order after the specified page. 
  * The command ''loopPage()'' interrupts the page order and returns to the "normal" page order after the repeated page. 
  * If a new page order is defined within a page order by using ''setPageOrder()'', the current page order will be broken and the new page order will be used. Once the new page order has been completed, the "normal" page order will be resumed.

**Note:** Filters can be inserted within the page order by using ''goToPage()''. If the filter jumps to a page within the ongoing page order, the sequence will be resumed there. If the filter jumps to a page outside of the page order, the normal page order in the questionnaire will be resumed from this page onwards.

In the following the use of ''setPageOrder()'' in connection with a [[:en:create:randomization]] or [[:en:create:rotation]] is illustrated by several examples.

===== Two possible processes =====

The following scenario should be implemented using ''setPageOrder()''. There are two question blocks  in the questionnaire: one of which is comprised of 5 pages and the other one of 7 pages. In one half of the questionnaire, Block A should be shown first and then Block B, and in the other half of the questionnaire, Block B should be shown first and then Block A. 

==== Preparations ====

Block A starts on page 5 (ID ''startA'') and ends on page 9 (ID ''endA''). Block B starts on page 10 (ID ''startB'') and ends on page 16 (ID ''endB''). The ID ''demography'' was given for page 17.

An urn defined with the ID ''order'' was set up for this scenario with the following content:

<code>
1
2
</code>

To save the urn draw, a question with the ID ''IV01'' with the type "internal variables" was defined, along with a variable within this question with the ID ''IV01_01''.

==== PHP Code ====

The following PHP code is now used on page 4 (or earlier on in the questionnaire):

<code php>
urnDraw('order', 'IV01');
$number = value('IV01_01');
if ($number == 1) {
  setPageOrder('startA-endA, startB-endB, demography');
} else {
  setPageOrder('startB-endB, startA-endA, demography');
}
</code>



===== Random sequence I =====

The questionnaire contains 5 pages that shall be displayed in random order.

==== Preparations ====

First, set individual IDs for each of the 5 pages (e.g., ''PA'' bis ''PE''). Second, set another ID for the page following ''PE'' (e.g., ''PX'').

==== PHP-Code ====

Place this code on the page preceding ''PA''.

<code php>
if (!isset($pages)) {
  $pages = array('PA', 'PB', 'PC', 'PD', 'PE');
  shuffle($pages);
  // Set the order of pages to use, and the page where to continue after that
  registerVariable($pages, 'PX');
}
setPageOrder($pages);
</code>

The combination of ''registerVariable()'' and ''isset()'' ensure that the shuffles page order will not be changed, if the page reloads (due to a "back" button the questionnaire provides, for example).

''shuffle()'' shuffles the 5 page list (array). Subsequently, the page ''PX'' is attached to the shuffled list, so it is always shown as last page.

**Note:** Should you need another rotation in the questionnaire, you'll need another variable than ''$pages''. Use ''$pages1'' for the first rotation, and ''$pages2'' for the second one, for example.

If the questionnaire does not show a "back" button, the PHP code may be simplified.

<code php>
$pages = array('PA', 'PB', 'PC', 'PD', 'PE');
shuffle($pages);
// Set the order of pages to use, and the page where to continue after that
setPageOrder($pages, 'PX');
</code>


===== Random sequence II =====

In this example there are 3 blocks (A, B, C) with 3 to 5 pages (A1, A2, A3, B1, ...). The order of the blocks should be shuffled randomly and additionally the pages should be shuffled within each block -- only the first one should always stay at the beginning.

**Note:** See also the example under Rotation -> [[:en:create:rotation#rotation_and_mix_of_blocks|Rotation and Mixing of Blocks]].

==== Preparation ====

If the individual pages are to be rotated, each page requires its own [[:en: glossary#page_ID]]. For the example the pages were named as follows: A1, A2, A3, B1 to B5, C1 to C4, and after C4 follows page D1, where the rotation should continue.

==== PHP-Code ====

<code php>
// First save the page labels as array
$rotation = array(
  'A' => array('A1','A2','A3'),
  'B' => array('B1','B2','B3','B4','B5'),
  'C' => array('C1','C2','C3','C4')
);
// Mix each block individually
foreach ($rotation as $key => $pages) {
  // Remove the first page from the array $pages
  $first = array_shift($pages);
  // Mix the rest
  shuffle($pages);
  // Put the two back together again
  array_unshift($pages, $first);
  // And save back to the $rotation array
  $rotation[$key] = $pages;
}

// Now mix the order of the blocks randomly
shuffle($rotation);

// Now set the result as page sequence
// Continue with page 'D1' afterwards
setPageOrder($rotation, 'D1');
</code>

===== Save sequence =====

In the survey project there are five topical question blocks. To simplify matters, these are put in sections ''R1'' to ''R5'' (this is optional). The question blocks are comprised of a different number of questions.  

The question blocks should now be shown in a random order to combat the order effect. The order they are shown in should be saved as well. 


==== Preparations ====

First of all, the questions are distributed over multiple pages. Initially, a few pages with questions from section ''R1'', then a few pages with questions from section ''R2'' and so on.

The first page with questions from section ''R1'' is given the ID ''R1start'' and the last page of this block is given the ID ''R1end''. The first and last pages of the other questions will also be given appropriate IDs. 

The page with a general section which comes after block R5 is given the ID ''demography''.

To save the order, a question is created with the ID ''IV01'' with the type "internal variables". Five variables are created within the question ("R1 to "R5"), which should save the position of the respective block later on. 

==== PHP Code ====

<code php>
$parts = array(
  'R1' => 'R1start-R1end',
  'R2' => 'R2start-R2end',
  'R3' => 'R3start-R3end',
  'R4' => 'R4start-R4end',
  'R5' => 'R5start-R5end'
);
// shuffle keys from the above array
$keys = array_keys($parts);
shuffle($keys);
// arrays now looks like: e.g. R2, R5, R3, R1, R4

// save position in shuffled array for each key
put('IV01_01', array_search('R1', $keys) + 1);
put('IV01_02', array_search('R2', $keys) + 1);
put('IV01_03', array_search('R3', $keys) + 1);
put('IV01_04', array_search('R4', $keys) + 1);
put('IV01_05', array_search('R5', $keys) + 1);

// now define page order 
setPageOrder(
  $parts[$keys[0]],  // $keys[0] is e.g. 'R2' and $parts['R2'] is 'R2start-R2end'
  $parts[$keys[1]],
  $parts[$keys[2]],
  $parts[$keys[3]],
  $parts[$keys[4]],
  'demography'
);
</code>