lab.js Experiment

lab.js (lab.js.org) is a JavaScript-based application used to conduct cognitive and behavioral science experiments through web browsers. The application allows for reaction time measurements, repetition of measurements, and randomization, among other features.

Experiments are built using the online platform lab.js builder (see lab.js documentation). The developer provides numerous examples in a repository, including among others a Balloon Analogue Risk Task, Flanker Task, N-Back Task, Paired Recall, Simon Task, Stroop Test, and Visual Search Task.

The finished experiment is exported as a ZIP file in the lab.js Builder (Export as integration → Generic survey tools) suitable for SoSci Survey. If you want to modify the experiment later, save the study as a JSON file via Save.

In SoSci Survey, create a new question of the “lab.js Experiment” type in a section of your choice. There, select the ZIP file you downloaded before at “lab.js ZIP export”. Decide using the “Full Screen” parameter whether the experiment should be displayed within the questionnaire, whether the entire browser window, or the entire screen should be used.

Save the question () and drag it to a page in the questionnaire in Compose Questionnaire. In most cases, it is useful to not place any other elements (questions, texts) on the questionnaire page next to the lab.js question.

lab.js experiments yield extensive data in a tabular data format – essentially a dataset with variables and data rows for each experimental run. It is advisable to consider early on how to calculate the information needed from each specific participant dataset.

Technically, SoSci Survey can store the data in two ways:

• As a text variable with the data encoded in JSON format. This option only works, if, after being JSON-encoded, the data size per experiment is less than 32 kB.
• The default is to download the data as separate files (one file per participant) using Collected Data → Download Uploaded Files.

Both options require substantial effort and knowledge in analysis of data. It is advisable to use advanced statistical software such as R to automate the reading and analysis of the experimental data.

There may be instances in which data from an interview needs to be passed to the lab.js experiment, such as the assignment to an experimental group or a participant identifier. This can be done by defining a corresponding JavaScript variable on the questionnaire page (JavaScript in the Questionnaire). These JavaScript variables can be accessed directly in the lab.js experiment.

Important: The HTML/JavaScript code should be inserted above the lab.js question on the same questionnaire page as the lab.js question.

The easiest way to define JavaScript variables is through the use of placeholders. In the following example, the predefined placeholders %caseNumber% and %caseSerial% are used, along with a third placeholder that is replaced with the contents of the variable “RG01”.

You can directly compose JavaScript code in Compose Questionnaire by including an “HTML code” element. To define the additional placeholder an additional line of PHP code is required.

replace('%valRG01%', 'RG01', 'response');

Followed by an “HTML code” block with the following content.

<script type="text/javascript">
var caseNumber = %caseNumber%;
var caseSerial = "%caseSerial%";
var expGroup   = %valRG01%;
</script>

Note the quotation marks for caseSerial, which is a string, not an integer like in the other two cases.

If you are working with the PHP function html(), substrings can be concatenated using a dot (.). The PHP code would then look like this.

html(
  '<script type="text/javascript">
  var caseNumber = %caseNumber%;
  var caseSerial = "%caseSerial%";
  var expGroup   = '.value('RG01').';
  </script>'
);

The predefined placeholders work in the same way as with “normal” HTML code. However, here the value of variable “RG01” is not inserted into the HTML code via a placeholder, but directly connected to the HTML code.

The HTML code can also be stored in a text within the list of questions. “HTML code” must be selected as Display for the text. The content is identical to the first option above.

<script type="text/javascript">
var caseNumber = %caseNumber%;
var caseSerial = "%caseSerial%";
var expGroup   = %valRG01%;
</script>

The difference is that the placeholder is directly replaced by the parameter in the function show(). If the above text has the identifier “JS02”, it would be integrated as follows.

show('JS02', [
    '%valRG01%' => value('RG01')
]);

Summary: <form> and <submit> elements must not be used if the experiment shall be included in a questionnaire. Furthermore, buttons may only be used with <button type="button"> (not with type="submit").

The lab.js Builder provides a BART experiment as a template. It does not work directly in SoSci Survey. The cause is the following section under “Judgment” → “Content”.

<p class="font-weight-bold">
  How far would you like to inflate the balloon?
</p>
<form id="pumps-form">
    <input
        type="range"
        name="pumps" id="pumps"
        class="w-100"
        min="1" max="128" step="1"
    >
</form>

A form element (<form>) generally does not work when included in SoSci Survey. The following change is necessary for the experiment to work correctly in SoSci Survey:

1. Remove the <form> element, but keep the contained <input> element.

<p class="font-weight-bold">
    How far would you like to inflate the balloon?
</p>
<input
    type="range"
    name="pumps" id="pumps"
    class="w-100"
    min="1" max="128" step="1"
>

2. In the same code, remove the part form="pumps-form" from the button (<button>), change the type from "submit" to "button" and add an ID (id="inflate").

<footer class="content-horizontal-right content-vertical-center">
  <button type="button" id="inflate">
    Inflate! &rarr;
  </button>
</footer>

3. Under “Judgment” → “Behavior”, add a response at “Responses” with the following details:

• label: submitted (freely selectable)
• action: “click”
• target: button#inflate
• filter: (remains empty)

Finally, export the experiment as a ZIP again (see above) and upload the ZIP file in the “lab.js” question in SoSci Survey.

There are some use cases in which the questionnaire runs within an HTML frameset (Play Music Across Several Pages, Frame Forwarding from Your Own Domain).

By default, lab.js uses a fallback mechanism that forwards the collected data to the parent frame. This mechanism, which is useful for an iFrame integration of lab.js, prevents the data from being stored in the questionnaire. The solution is to add some JavaScript to the frameset HTML that redirects the data to the questionnaire. This can look as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8">
      <title>Questionnaire</title>
      <script>
      window.addEventListener('message', function(e) {
        if (e.data && e.data.type === 'labjs.data') {
          var soSciFrame = document.getElementById('sosciFrame');
          if (soSciFrame) {
            soSciFrame.contentWindow.postMessage(e.data, '*');
          }
        }
      });
  </script>
  </head>
 
  <frameset rows="99%, 1%" border="0">
	<frame src="./index.php" name="survey" id="sosciFrame">
	<frame src="./music.html" name="music">
  </frameset>
</html>

Important: The questionnaire frame must have an ID (in the example id="sosciFrame") and the same ID must be used in the JavaScript (in the example document.getElementById('sosciFrame')).