Randomize Media Files

Images, videos and audio files can be randomized using PHP code. Therefore the files get included with HTML texts. The files must already be stored in images and media files (see also Images in the Questionnaire and media files in questionnaire).

Note: Since the inclusion of the stimuli is already the 2nd step of a randomization, be sure to read the Randomization with PHP-Code chapter first, as it describes exactly how to create the required Random Generator (step 1) and where to place your PHP code on the page.

Tip: Media files can also be randomized using only a random generator and HTML. Read the chapter Single Factorial Experimental Design, in most cases this simpler approach is sufficient.

How the PHP codes for the individual file types can look like is described in more detail below. In general, however, the PHP codes look the same, because the files are each created as HTML texts (see Media Files in Questionnaires (Audio, Video, Documents)) and then displayed.

Tip: This option offers a lot of room for design and editing for more complex representations through the HTML text (see below: example of extensive HTML codes). For simpler inclusion of images, the option described in Single Factorial Experimental Design is more suitable.

If there are 2 images to randomize in your example, the corresponding PHP code to include them using HTML text could look like this:

if (value('RG01') == 1) {
  text('BT01');
  //The shown text is the HTML-Text of the image with the ID BT01
} elseif (value('RG01') == 2) {
  text('BT02');
  //The shown text is the HTML-Text of the image with the ID BT02
}

Especially in experiments, it is often necessary to randomly distribute participants between experimental and control groups or, in other words, to randomly choose which of several stimuli to display.

The following example shows how to randomize one of 4 images using PHP code. The prerequisite is that – as described above – a random number between 1 and 4 is drawn and stored in a variable (random generator). In addition, the 4 images must be uploaded to the survey project in advance under Images and Media Files. In the exaple are randomly the images “stimulus1.png”, “stimulus2.png”, “stimulus3.png” or “stimulus4.png” displayed. Underneath, for example, a question about the rating of the image could be displayed. This would have to be placed under the PHP code when Compose Questionnaire, then all participants will get different stimuli, but always the same question about them:

$number = value('RG01');  // Reading the drawn random number
 
// Display graphic depending on the number
// (therefore we use HTML code)
if ($number == 1) {
  html('<p><img src="stimulus1.png"></p>');
} elseif ($number == 2) {
  html('<p><img src="stimulus2.png"></p>');
} elseif ($number == 3) {
  html('<p><img src="stimulus3.png"></p>');
} elseif ($number == 4) {
  html('<p><img src="stimulus4.png"></p>');
}

Instead of using html() to show a text or a graphic, you can of course use text() to show a longer text, embed a video or use question() to show a question.

The following PHP code can also be used to include images, but it does not work with complete pieces of HTML code, but with a placeholder %filename% and the function replace().

$code = value('RG01');  // Reading the drawn random number
 
// Write graphic file into a placeholder depending on the random number
if ($code == 1) {
  replace('%filename%', 'stimulus1.png');
} elseif ($code == 2) {
  replace('%filename%', 'stimulus2.png');
} elseif ($code == 3) {
  replace('%filename%', 'stimulus3.png');
} elseif ($code == 4) {
  replace('%filename%', 'stimulus4.png');
}
// You can include the HTML code directly or (not shown here) as a text module
html('<p><img src="%filename%"></p>');

Tip: Placeholders are especially helpful when more HTML code is required to include the stimulus than shown here as an example.

Tip: The name of the PHP variable (in the examples $number and $code) is arbitrarily chosen. For more information, see PHP variables.

The PHP codes above have only used the (numerical) code drawn by the random generator. However, you can also use the content of the slips of paper in the random generator. If you are working with images, it is a good idea to store the image names in the random generator. For example

1 = stimulus1.png
2 = stimulus2.png
3 = stimulus3.png
4 = stimulus4.png
5 = stimulus5.png
6 = stimulus6.png

While you use value('RG01') to access the numeric code, you can use value('RG01', 'label') to access the content of the code that was drawn. Using replace('%image%', 'RG01', 'response') you can also write the content directly into a placeholder.

The previous PHP code can thus be written as follows.

question('RG01');
replace('%filename%', 'RG01', 'response');
html('<p><img src="%filename%"></p>');

If you draw several codes during an interview, you only have to adjust the name of the variable according to the Variables Listing, e.g.

question('RG01');
// Show the image according to the first code drawn
replace('%filename1%', 'RG01x1', 'response');
html('<p><img src="%filename1%"></p>');
// Show the image according to the second code drawn
replace('%filename2%', 'RG01x2', 'response');
html('<p><img src="%filename2%"></p>');

Videos can also be embedded using a text() function. Therefore you need the same code as for the texts and embed the video via HTML text. The videos have to be saved in Images and Mediafiles and written in a Text.

A code in which one control group is shown no stimulus and the other two groups are randomized to two videos might look like this:

if (value('RG01') == 2) {
  text('VT01');
  //HTML text of the video with the ID VT01
} elseif (value('RG01') == 3) {
  text('VT02');
  //HTML text of the video with the ID VT02
}

Audio files can also be embedded using a text() function. To do this, you need the same code as for the texts and embed the audio via PHP-Code on the corresponding questionnaire page (see step2). The HTML text of the individual audios already specifies how they are to be displayed and played. For a more detailed explanation, be sure to read the chapters Include audio files and Text Elements and again save the audio files beforehand under Images and Media Files.

The PHP code to include the audio files on the questionnaire page could look like this if there are 3 groups and only 2 groups should have audio played to them (a control group without audio).

if (value('RG01') == 2) {
  text('AT01');
  //HTML text ot the audio with the ID AT01
} elseif (value('RG01') == 3) {
  text('AT02');
  //HTML text ot the audio with the ID AT02
}

If stimuli require extensive HTML code (e.g., videos), if the HTML code differs greatly between experimental groups, or if working with a multilingual questionnaire, four texts are created in the questionnaire (e.g., “RG02” to “RG05”, presentation each HTML code) and included depending on the random draw:

$code = value('RG01');  // Reading the drawn random number
 
// Display text respectively HTML code as text
if ($code == 1) {
  text('RG02');
} elseif ($code == 2) {
  text('RG03');
} elseif ($code == 3) {
  text('RG04');
} elseif ($code == 4) {
  text('RG05');
}