Rotation: Items

This chapter describes how to present the individual items in a question in a random order and how the several ways to implemt this work.

Randomization or rotation of items in a question is enabled as follows:

• Open the question in the “List of Questions”
• In the Response Options or Items section, select the Settings tab..
• In the setting Order select the option “Shuffle/rotate randomly”.
• Save the question , in the preview you can check the rotation.

If you want to exclude individual items (e.g. an “Other” with text input) from the rotation, open this item in the List of Questions or with the icon and activate the Exclude this item during sorting/shuffling option.

Note: The rotation of course only concerns the representation in the questionnaire. The respondent's answers to a given item are always stored under the same identifier.

Note: The sequence in which the items are displayed is not saved in the data set. If you need this information, unse the rotation per PHP code (see below).

It is possible to rotate items or options of questions per PHP-code. To do this, first a list of items/options is retrieved via getItems(), then shuffled via shuffle() and finally the question is displayed via question() with the desired item sequence as parameter.

$items = getItems('AB01', 'all');
shuffle($items);
question('AB01', $items);

This procedure offers the possibility to save the displayed sequence in the data set. It is done using internal variables and the command put().

Note, however, that here (unlike button rotation) the order changes as soon as the participant reloads the page or uses the back button in the questionnaire. UseregisterVarible() and isset() to prevent this. So the random sequence is only rolled the first time the page is loaded – the next time it is loaded, the variable $itemsAB is already set (isset() stands for “is set”) and that part is skipped.

if (!isset($itemsAB)) {
  $itemsAB = getItems('AB01', 'all');
  shuffle($itemsAB);
  registerVariable($itemsAB);
}
question('AB01', $itemsAB);

Note: After a variable stored using registerVariable() is available on all pages of the questionnaire, you can not use the same PHP code to rotate the items of another question - because the variable is already set. For another question just use another name for the variable (e.g. $itemsCD).

Manual rotation (see above) allows you to use the same rotated item sequence in two or more questions. If the questions are on different pages, use registerVariable() for this as well – just like in the example above – to make the sequence available to other PHP code elements.

if (!isset($itemsAB)) {
  $itemsAB = getItems('AB01', 'all');
  shuffle($itemsAB);
  registerVariable($itemsAB);
}
question('AB01', $itemsAB);

On the same or later pages, the order as stored in $itemsAB can easily be used for other questions.

question('AB02', $itemsAB);

If you have many items in a question you may want to display them over several pages. Normally, you would do this by inserting the question multiple times when Compose Questionnaire and specifying different items each time in the display settings ( button), e.g. “1-10”, “11-20”, etc.

If you want to combine item distribution with randomization, you need a few lines of PHP code.

// The isset() prevents, that the rotation gets changed because of for example missing answers
if (!isset($itemsAB01)) {
  // List all items of the question AB01 
  $itemsAB01 = getItems('AB01', 'all');
  // Mix list
  shuffle($itemsAB01);
  // Devide list in sublists à 20 Items 
  $itemsAB01 = array_chunk($itemsAB01, 20);
  // Make the variable available for other pages
  registerVariable($itemsAB01);
}
 
// Display items over several pages
$i = loopPage(count($itemsAB01));
question('AB01', $itemsAB01[$i]);

With the function loopPage() you can display several different pages within one questionnaire page. As an alternative to the last two lines, you can insert the required number of pages in the questionnaire and display the corresponding item area in each case:

// First page
question('AB01', $itemsAB01[0]);
 
// Second page
question('AB01', $itemsAB01[1]);
 
// Third page
question('AB01', $itemsAB01[2]);

Please note that only the index in square brackets will change on the pages. The index starts at 0, not at 1 (see example above).

Important: If you directly start a page with items when Compose Questionnaire, you get the error message that the variable $itemsAB01 is unknown. For testing you have to start each time from the page where the randomization begins and thus the variable $itemsAB01 is defined.

As a general rule, it is easier to have the items to be rotated all in one question. In the Variables tab, the variable names can also be adapted, if necessary, so that the different affiliation to constructs/sub-scales can be easily understood in the evaluation.

However, there are situations when it is necessary to mix items from different questions. For example, if they are scale items that use different response options. As a basis for the rotation you first need an array, which in turn contains arrays with question and item identifiers.

Of course you can define this item list manually, this looks like this for two questions (AB01 and AB02) with 4 items each:

$itemliste = [
  ['AB01', 1],
  ['AB01', 2],
  ['AB01', 3],
  ['AB01', 4],
  ['AB02', 1],
  ['AB02', 2],
  ['AB02', 3],
  ['AB02', 4]
];

If you want to use all items of the questions anyway, you can also read them automatically using getItems(). DThis would be as follows:

$questions = ['AB01', 'AB02'];
$itemlist = [];
foreach ($questions as $question) {
  foreach (getItems($question, 'all') as $item) {
    $itemsliste[] = [$question, $item];
  }
}

The shuffling of the item list is done by means of shuffle()..

shuffle($itemlist);

To display each item, the question() function must be called individually – this will display the question with only one item at a time. So that the question text does not appear again and again, the parameter show-title=no must be set. In addition, spacing=0 ensures that there is not too much space between the items. So that the question text is nevertheless displayed once above the question, question() is also called again with show-items=none.

question('AB01', 'show-items=none', 'spacing=0');
foreach ($itemlist as $info) {
  $question = $info[0];
  $item = $info[1];
  question($question, $item, 'show-title=no', 'show-explanation=no', 'spacing=0');
}

The three PHP-codes for creating the itemlist, mixing and displaying have to be written in one PHP-code. If it is theoretically possible that the page is redisplayed due to a response requirement or by the back button, you can still use registerVariable() and isset() to ensure that the list is shuffled only once. The hole PHP-code then looks like this:

$questions = ['AB01', 'AB02'];
$itemlist = [];
foreach ($questions as $question) {
  foreach (getItems($question, 'all') as $item) {
    $itemslist[] = [$question, $item];
  }
}
 
// mixing
if (!isset($itemMix)) {
  $itemMix = $itemliste;
  registerVariable($itemMix);
}
 
// display questiontext
question('AB01', 'show-items=none', 'spacing=0');
 
// display items individual
foreach ($itemMix as $info) {
  $question = $info[0];
  $item = $info[1];
  question($question, $item, 'show-title=no', 'show-explanation=no', 'spacing=0');
}

The last part can also be modified using loopPage() so that each item (or blocks of e.g. 3 items each) are displayed on a separate page.