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

Normalerweise werden die Seiten im Fragebogen von der ersten bis zur letzten Seite sequenziell abgearbeitet, falls diese Reihenfolge nicht durch ''[[:de:create:functions:setnextpage|setNextPage()]]'' oder ''[[:de:create:functions:gotopage|goToPage()]]'' unterbrochen wird.

Mit der Funktion ''setPageOrder()'' lässt sich von vornherein eine andere Seitenabfolge festlegen. Dies kann zu einem beliebigen Zeitpunkt im Fragebogen geschehen. Die neue //Seitenabfolge// wird ab den nächsten Klick auf "Weiter" verwendet (der Fragebogen startet also in jedem Fall mit Seite 1).

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

  * //Seitenabfolge//\\ Eine oder mehrere Seiten-Kennungen, die als Array oder als Komma-separierte Liste angegeben werden. Seitenbereiche können durch einen Bindestrich angegeben werden, s. Beispiele:

^Seitenabfolge^Effekt^
|'''pageA, pageB, pageC, pageD'''|Zeigt nacheinander die Seiten mit der Kennung ''pageA'', ''pageB'', ''pageC'' und ''pageD''|
|''array('pageA','pageB','pageC','pageD')''|:::|
|'''pageA-pageD'''|Zeigt alle Seiten von ''pageA'' bis ''pageD''|
|'''pageA-pageD, pageE-pageK'''|Zeigt zunächst die Seiten von ''pageA'' bis ''pageD'' und anschließend die Seiten von ''pageE'' bis ''pageK''|
|''array('pageA-pageD','pageE-pageK')''|:::|
|'''pageA-pageD,pageE,pageC,end'''|Zeigt zunächst alle Seiten von ''pageA'' bis ''pageD'', dann nacheinander die Seiten ''pageE'' und ''pageC'' und beendet dann den Fragebogen mit der letzten Seite.|

Nachdem die definierte Seitenabfolge abgearbeitet wurde, wird die Seite angezeigt, die in der "normalen" Abfolge auf die letzte Seite der Seitenabfolge folgt.

**Wichtig:** Die Befehle ''setNextPage()'', ''loopPage()'' und ''setPageOrder()'' unterbrechen eine Seitenabfolge:

  * Der Befehl ''setNextPage()'' unterbricht eine Seitenabfolge und kehrt nach der angegeben Seite zur "normalen" Seitenfolge zurück.
  * Der Befehl ''loopPage()'' unterbricht eine Seitenabfolge und kehrt nach der wiederholten Seite zur "normalen" Seitenfolge zurück.
  * Wird innerhalb einer Seitenabfolge eine neue Seitenabfolge mittels ''setPageOrder()'' definiert, so wird die aktuelle Seitenabfolge unterbrochen und die neue Seitenabfolge verwendet. Nach Abschluss der neuen Seitenabfolge wird mit der "normalen" Seitenabfolge fortgesetzt.

**Hinweis:** Innerhalb der Seitenabfolge können Filter mittels ''goToPage()'' eingesetzt werden. Falls der Filter zu einer Seite innerhalb der laufenden Seitenabfolge springt, wird die Seitenfolge dort fortgesetzt. Falls der Filter auf eine Seite außerhalb der Seitenabfolge springt, wird die Befragung ab dieser Seite in der "normalen" Seitenabfolge fortgesetzt.

Nachfolgend wird die Verwendung von ''setPageOrder()'' in Verbindung mit einer [[:de:create:randomization]] oder [[:de:create:rotation]] anhand mehrere Beispiele veranschaulicht.


===== Zwei mögliche Abläufe =====

Folgendes Szenario soll mittels ''setPageOrder()'' realisiert werden: Im Fragebogen gibt es zwei Frageblöcke, die einmal 5 Seiten umfassen und einmal 7 Seiten. In der Hälfte der Interviews soll zunächst Block A und dann Block B angezeigt werden, bei der anderen Hälfte der Interviews soll zunächst Block B und dann Block A angezeigt werden.

==== Vorbereitungen ====

Block A beginnt auf Seite 5, welche die Kennung ''startA'' hat und endet auf Seite 9, welche die Kennung ''endeA'' hat. Block B beginnt auf Seite 10 (Kennung ''startB'') und endet auf Seite 16 (Kennung ''endeB''). Für Seite 17 wurde die Kennung ''demografie'' eingestellt.

Für das Szenario wurde eine Urne mit der Kennung ''reihenfolge'' definiert mit folgendem Inhalt:

<code>
1
2
</code>

Zum Speichern der Urnen-Ziehung wurde eine Frage mit der Kennung ''IV01'' vom Typ "interne Variablen" definiert und innerhalb dieser Frage eine Variable mit der Kennung ''IV01_01''.

==== PHP-Code ====

Folgender PHP-Code wird nun auf Seite 4 (oder früher im Fragebogen) verwendet:

<code php>
urnDraw('reihenfolge', 'IV01');
$zahl = value('IV01_01');
if ($zahl == 1) {
  setPageOrder('startA-endeA, startB-endeB, demografie');
} else {
  setPageOrder('startB-endeB, startA-endeA, demografie');
}
</code>


===== Zufällige Abfolge I =====

Im Befragungsprojekt gibt es 5 Seiten, die in zufälliger Reihenfolge angezeigt werden sollen. 

==== Vorbereitung ====

Zunächst bekommen die 5 Seiten individuelle Kennungen (z.B. ''PA'' bis ''PE''). Auch die Seite, die nach ''PE'' folgt, bekommt eine Kennung (z.B. ''PX'').

==== PHP-Code ====

Auf der Seite, die vor ''PA'' kommt, wird folgender PHP-Code platziert.

<code php>
if (!isset($seiten)) {
  $seiten = array('PA', 'PB', 'PC', 'PD', 'PE');
  shuffle($seiten);
  registerVariable($seiten);
}
// Die Seitenabfolge festlegen und die Seite, wo es anschließend weitergeht
setPageOrder($seiten, 'PX');
</code>

Das ''isset()'' in Kombination mit dem ''registerVariable()'' sorgt dafür, dass die Reihenfolge beim Neu-Laden der Seite (z.B. weil der Fragebogen einen "Zurück"-Knopf erlaubt) nicht verändert wird.

Mit ''shuffle()'' wird die Liste der 5 Seiten gemischt, anschließend wird die Seite ''PX'' an die Liste angehängt, damit diese stets als letzte gezeigt wird.

**Hinweis:** Falls im Fragebogen eine weitere Rotation zum Einsatz kommen soll, muss dafür eine andere Variable als ''$seiten'' verwendet werden. So könnte man z.B. für die erste Rotation ''$seiten1'' und in der zweiten Rotation ''$seiten2'' verwenden.

Falls der Fragebogen keinen "Zurück"-Knopf erlaubt, kann der PHP-Code noch ein wenig vereinfacht werden.


<code php>
$seiten = array('PA', 'PB', 'PC', 'PD', 'PE');
shuffle($seiten);
// Die Seitenabfolge festlegen und die Seite, wo es anschließend weitergeht
setPageOrder($seiten, 'PX');
</code>


===== Zufällige Abfolge II =====

In diesem Beispiel gibt es 3 Blöcke (A, B, C) mit 3 bis 5 Seiten (A1, A2, A3, B1, ...). Die Reihenfolge der Blöcke soll zufällig gemischt werden und zusätzlich sollen innerhalb jedes Blocks die Seiten gemischt werden -- nur die erste soll immer zu Beginn bleiben.

**Hinweis:** Sehen Sie sich zu diesem Beispiel auch das Beispiel unter Rotation -> [[:de:create:rotation#rotation_und_mischen_von_bloecken|Rotation und Mischen von Blöcken]] an.

==== Vorbereitung ====

Wenn die einzelnen Seiten rotiert werden sollen, benötigt jede Seite eine eigene [[:de:glossary#seitenkennung|Seiten-Kennung]]. Für das Beispiel wurden die Seiten wie folgt benannt: A1, A2, A3, B1 bis B5, C1 bis C4 und nach C4 folgt noch die Seite D1, wo es nach der Rotation immer weitergehen soll.

==== PHP-Code ====

<code php>
// Erst einmal die Seitenkennungen als Array speichern
$rotation = array(
  'A' => array('A1','A2','A3'),
  'B' => array('B1','B2','B3','B4','B5'),
  'C' => array('C1','C2','C3','C4')
);
// Jeden Block einzeln mischen
foreach ($rotation as $key => $pages) {
  // Die erste Seite aus dem Array $pages herausnehmen
  $first = array_shift($pages);
  // Den Rest mischen
  shuffle($pages);
  // Beides wieder zusammenfügen
  array_unshift($pages, $first);
  // Und in das Array $rotation zurückspeichen
  $rotation[$key] = $pages;
}

// Jetzt noch die Reihenfolge der Blöcke zufällig mischen
shuffle($rotation);

// Jetzt das Ergebnis noch als Seitenabfolge festlegen
// Weiter soll es anschließend mit Seite 'D1' gehen
setPageOrder($rotation, 'D1');
</code>


===== Reihenfolge speichern =====

Im Befragungsprojekt gibt es fünf thematische Frageblöcke. Der Einfachheit halber wurden diese in die Rubriken ''R1'' bis ''R5'' gepackt (das ist optional). Die Frageblöcke umfassen eine unterschiedliche Anzahl an Fragen.

Die Frageblöcke sollen nun in zufällige Reihenfolge angezeigt werden, um Reihenstellungseffekte zu kontrollieren. Dabei soll die Reihenfolge abgespeichert werden.

==== Vorbereitungen ====

Die Fragen werde zunächst auf mehrere Seiten im Fragebogen verteilt. Zunächst einige Seiten mit Fragen aus Rubrik ''R1'', dann einige Seiten mit Fragen aus Rubrik ''R2'' u.s.w.

Die erste Seite mit Fragen aus Rubrik ''R1'' bekommt die Kennung ''R1start'', die letzte Seite dieses Blocks die Kennung ''R1ende''. Entsprechend werden auch die ersten und letzten Seite der anderen Frage mit Kennungen versehen.

Die Seite mit einem allgemeinen Teil, der nach Block R5 folgt, bekommt die Kennung ''demografie''.

Zum Speichern der Reihenfolge wird eine Frage mit der Kennung ''IV01'' vom Typ "interne Variablen" angelegt. Darin werden fünf Variablen angelegt (Beschreibung "R1" bis "R5"), welche später die Position des jeweiligen Blocks speichern sollen.

==== PHP-Code ====

<code php>
$parts = array(
  'R1' => 'R1start-R1ende',
  'R2' => 'R2start-R2ende',
  'R3' => 'R3start-R3ende',
  'R4' => 'R4start-R4ende',
  'R5' => 'R5start-R5ende'
);
// Die Schlüssel des obigen Arrays mischen
$keys = array_keys($parts);
shuffle($keys);
// Das Array sieht nun z.B. so aus: R2, R5, R3, R1, R4

// Für jeden Schlüssel die Position im gemischten Array abspeichern
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);

// Jetzt noch die Seitenabfolge definieren
setPageOrder(
  $parts[$keys[0]],  // $keys[0] ist z.B. 'R2' und $parts['R2'] ist 'R2start-R2ende'
  $parts[$keys[1]],
  $parts[$keys[2]],
  $parts[$keys[3]],
  $parts[$keys[4]],
  'demografie'
);
</code>