====== 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.

===== Example 1 =====

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>



===== Example 2 =====

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);
  $pages[] = 'PX';
  registerVariable($pages);
}
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);
$pages[] = 'PX';
setPageOrder($pages);
</code>



===== Example 3 =====

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>