setPageOrder()

Normally, pages in the questionnaire executed consecutively from the first to the last page provided that setNextPage() or 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:

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 Randomization or Rotation is illustrated by several examples.

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.

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:

1
2

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.

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

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

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

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

Place this code on the page preceding PA.

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);

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.

$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');

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 → Rotation and Mixing of Blocks.

If the individual pages are to be rotated, each page requires its own 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.

// 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');

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.

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.

$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'
);