====== urnDraw() ======

''int|false **urnDraw**(string //UrnenKennung//, string //FrageKennung//, [string //Ablegen//])''

Mit urnDraw() entnehmen Sie einen Zettel (eine Zahl oder eine Kombination mehrerer Werte) aus einer Urne. Wenn alle Zettel aus der Urne gezogen und abgelegt wurden, dann wird die Urne von Neuem gefüllt.

Details zur Verwendung von Urnen finden Sie im Kapitel [[:de:create:random_urns|Randomisierung mit Urnen]].

  * //UrnenKennung//\\ Die Kennung der Urne gibt an, aus welcher Urne der Zettel gezogen werden soll.
  * //FrageKennung//\\ Geben Sie hier die Kennung einer Frage vom Typ //interne Variablen// an, in welcher die gezogene Kombination gespeichert werden soll.
  * //Ablegen//\\ Hier können Sie festlegen, ob die Kombination sofort abgelegt werden soll oder erst später. Falls Sie nichts angeben, wird die Kombination sofort abgelegt.
    * '''now''' Die Kombination wird sofort abgelegt
    * '''end''' Die Kombination wird abgelegt, wenn/falls der Teilnehmer die //letzte Seite// des Fragebogens erreicht
    * '''man''' Die Kombination wird manuell durch Aufruf von ''[[urnputaway|urnPutAway()]]'' abgelegt
    * '''no''' Die Kombination wird gar nicht abgelegt -- es wird eine Ziehung mit Zurücklegen durchgeführt

===== Rückgabewert =====

Die Funktion liefert im Normalfall eine Zahl (''int'') zurück, zum wievielten Male die Urne gerade geleert wird. Für eine neu angelegte (oder zurückgesetzte) Urne wird die ''1'' zurückgegeben. Wurde die Urne einmal vollständig geleert, wird bei der nächsten Ziehung mittels ''urnDraw()'' die ''2'' zurückgegeben.

Für den Fall, dass bei der Ziehung ein Fehler auftritt (z.B. ungültige //UrnenKennung// oder //FrageKennung//) wird der Bool'sche Wert ''false'' zurückgegeben.

===== Hinweise =====

**Hinweis:** Falls innerhalb eines Interviews mehrere Kombinationen aus derselben Urne gezogen werden sollen, müssen unterschiedliche Frage-Kennungen angegeben werden.

**Hinweis:** In den internen Variablen dürfen vor der Ziehung noch keine Werte gespeichert worden sein, z.B. via ''put()''.

**Hinweis:** Damit sich Interviewpartner nicht nach Belieben eine Kombination auswählen können, wird pro Interview nur einmal gezogen und -- falls die Person die Seite mit der Ziehung nochmals aufruft -- diese Ziehung auch beibehalten. Das heißt, dass Sie beim Testen durch Aktualisieren der Browser-Ansicht __immer den gleichen__ Zettel bekommen werden. Um einen neuen Zettel zu bekommen, müssen Sie den Fragebogen neu starten.

===== Beispiel 1 =====

Im folgenden Beispiel wird ein Zettel aus der Urne "Personen" gezogen (diese Urne enthält Kombinationen aus jeweils 2 Zahlen) und die gezogene Kombination in den Variablen von IV01 gespeichert. Anschließend wird die gezogene Kombination einfach nur angezeigt.

<code php>
urnDraw('Personen', 'IV01');
html('<p>Auf dem Zettel steht die Kombination '.value('IV01_01').' - '.value('IV01_02').'</p>');
</code>

**Hinweis:** Im einfachsten Fall besteht eine Kombination nur aus einem einzigen Wert.

**Hinweis:** Lesen Sie für umfangreiche Beispiel das Kapitel [[:de:create:randomization|Randomisierung]].


===== Beispiel 2 =====

Mithilfe des Rückgabewerts können Sie die Erhebung beenden, wenn die Urne ausreichend oft geleert wurde. Der folgende PHP-Code zeigt nach der dritten Leerung (also wenn jeder Zettel 3-mal gezogen wurde) den Textbaustein "over" an und blendet zugleich den //Weiter//-Knopf aus.

<code php>
$round = urnDraw('Personen', 'IV01');
if ($round > 3) {
  text('over'); // Den entsprechenden Textbaustein muss man unter "Textbausteine und Beschriftung" anlegen
  buttonHide();  // Blendet alle Knöpfe aus
  pageStop();  // Führt keine weiteren Inhalte auf der Seite mehr aus (falls unter dem PHP-Code noch Fragen, Texte o.ä. stehen)
}
</code>