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 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()
  • 'no' The combinaton will not be stored at all – a draw with replacement will be carried out.

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.

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.

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.

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

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

Note: Read the chapter Randomization for comprehensive examples.

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

$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) 
}