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

''int|false **urnDraw**(string //urnID//, string //questionID//, [string //store//])''

A ballot (a number or a combination of several values) is taken out of an urn with urnDraw(). Once all ballots have been drawn from the urn and stored, the urn will be refilled.

For details regarding the use of urns, please see the chapter [[:en:create:random_urns|Randomization with Urns]].

  * //urnID//\\ The urn ID indicates which urn the ballot should be taken from.
  * //questionID//\\ Specify the ID of a question with the type //internal variables// here, in which the drawn combination should be stored. 
  * //store//\\ Here you can determine whether should the combination should be stored immediately, or at a later time. If you do not specify anything, the combination will be stored immediately.
    * '''now''' The combination will be stored immediately
    * '''end''' The combination will be stored when/if the participant reaches the //last page// in the questionnaire.
    * '''man''' The combination will be stored manually by calling up ''[[urnputaway|urnPutAway()]]'' 
    * '''no''' The combinaton will not be stored at all -- a draw with replacement will be carried out.


===== Return Value =====

Normally, the function returns the number (''int'') of times the urn has been emptied. For a newly created urn, or one that has been reset, ''1'' is returned. If the urn was completely emptied once, ''2'' will be returned on the next draw when ''urnDraw()'' is used.

In the event that an error occurs during the draw (e.g. invalid //urnID// or //questionID//), the Boolean value ''false'' will be returned. 


===== Tips =====

**Note:** If several combinations should be drawn out of the same urn within a questionnaire, different question IDs have to be specified.

**Note:** There must be no values saved in the internal values before the draw, e.g. with ''put()''.

**Note:** To prevent the respondent from being able to select a combination at their own free will, only one combination will be drawn per questionnaire and -- if the person calls up the page with the draw again -- this draw will also be kept. If you refresh the browser display to test this, it means that will __always get the same__ ballot. In order to get a new ballot, you have to restart the questionnaire.

===== Example 1 =====

In the following example, a ballot is drawn out of the urn "people" (this urn contains combinations each made up of 2 numbers), and the combination drawn is saved in the variables from IV01. Following this, the combination drawn will just be displayed.


<code php>
urnDraw('people', 'IV01');
html('<p>The combination is on the ballot '.value('IV01_01').' - '.value('IV01_02').'</p>');
</code>

**Note:** In the simplest case, a combination just consists of a single value. 

**Note:** Read the chapter [[:de:create:randomization|Randomization]] for comprehensive examples.


===== Example 2 =====

With the help of the return value, you can end the survey when the urn is emptied a sufficient number of times. The following PHP code both displays the text element "over", and hides the //Next// button after the third collection (i.e. when each ballot has been drawn 3 times).


<code php>
$round = urnDraw('people', 'IV01');
if ($round > 3) {
  text('over'); // corresponding text element has to be created in "Text Elements and Labels"
  buttonHide();  // hides all buttons
  pageStop();  // no other content is run on the page (provided there are still questions, text etc. below the PHP code) 
}
</code>