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


===== Rotation in a Question =====

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 {{:button.save.png?nolink|}}, 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 {{:button.edit.gif?nolink|Edit}} 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 [[:en:create:php|PHP code]] (see below).


===== Manual Rotation of Items or Orptions =====

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 ''[[:en:create:functions:getitems]]'', then shuffled via ''shuffle()'' and finally the question is displayed via ''[[:en:create:functions:question]]'' with the desired item sequence as parameter.

<code php>
$items = getItems('AB01', 'all');
shuffle($items);
question('AB01', $items);
</code>

This procedure offers the possibility to save the displayed sequence in the data set. It is done using internal variables and the command ''[[:en:create:functions:put#examplerandomization_i|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. Use''registerVarible()'' 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.

<code php>
if (!isset($itemsAB)) {
  $itemsAB = getItems('AB01', 'all');
  shuffle($itemsAB);
  registerVariable($itemsAB);
}
question('AB01', $itemsAB);
</code>

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


===== Parallel Rotation of Items in Two Questions =====

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 ''[[:en:create:functions:registervariable]]'' for this as well -- just like in the example above -- to make the sequence available to other PHP code elements.

<code php>
if (!isset($itemsAB)) {
  $itemsAB = getItems('AB01', 'all');
  shuffle($itemsAB);
  registerVariable($itemsAB);
}
question('AB01', $itemsAB);
</code>

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

<code php>
question('AB02', $itemsAB);
</code>


===== Rotation of Questions over several Pages =====

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.settings.png?nolink|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|PHP code]].

<code php>
// 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]);
</code>

With the function ''[[:en:create:functions:looppage|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:

<code php>
// First page
question('AB01', $itemsAB01[0]);

// Second page
question('AB01', $itemsAB01[1]);

// Third page
question('AB01', $itemsAB01[2]);
</code>

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.


===== Rotate Items of different Questions =====

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.

==== Variant 1: Create Array Manually ====

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

<code php>
$itemliste = [
  ['AB01', 1],
  ['AB01', 2],
  ['AB01', 3],
  ['AB01', 4],
  ['AB02', 1],
  ['AB02', 2],
  ['AB02', 3],
  ['AB02', 4]
];
</code>


==== Variant 2: Create Array Automatically ====

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

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


==== Mix and Display Items ====

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

<code php>
shuffle($itemlist);
</code>

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

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

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:

<code php>
$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');
}
</code>

The last part can also be modified using ''[[:en:create:functions:looppage]]'' so that each item (or blocks of e.g. 3 items each) are displayed on a separate page.