Skip to content

external-html

Current version: 1.1.3. See version history.

The HTML plugin displays an external HTML document (often a consent form). Either a keyboard response or a button press can be used to continue to the next trial. It allows the experimenter to check if conditions are met (such as indicating informed consent) before continuing.

Parameters

In addition to the parameters available in all plugins, this plugin accepts the following parameters. Parameters with a default value of undefined must be specified. Other parameters can be left unspecified if the default value is acceptable.

Parameter Type Default Value Description
url string undefined The URL of the page to display.
cont_key string null The key character the participant can use to advance to the next trial. If left as null, then the participant will not be able to advance trials using the keyboard.
cont_btn string null The ID of a clickable element on the page. When the element is clicked, the trial will advance.
check_fn function function(){ return true; } This function is called with the jsPsych display_element as the only argument when the participant attempts to advance the trial. The trial will only advance if the function return true. This can be used to verify that the participant has correctly filled out a form before continuing, for example.
force_refresh boolean false If true, then the plugin will avoid using the cached version of the HTML page to load if one exists.
execute_script boolean false If true, then scripts on the remote page will be executed.

Data Generated

In addition to the default data collected by all plugins, this plugin collects the following data for each trial.

Name Type Value
url string The URL of the page.
rt numeric The response time in milliseconds for the participant to finish the trial.

Simulation Mode

In visual simulation mode, the plugin cannot interact with any form elements on the screen other than the cont_btn specified in the trial parameters. If your check_fn requires other user interaction, for example, clicking a checkbox, then you'll need to disable simulation for the trial and complete the interaction manually.

Install

Using the CDN-hosted JavaScript file:

<script src="https://unpkg.com/@jspsych/plugin-external-html@1.1.3"></script>

Using the JavaScript file downloaded from a GitHub release dist archive:

<script src="jspsych/plugin-external-html.js"></script>

Using NPM:

npm install @jspsych/plugin-external-html
import externalHtml from '@jspsych/plugin-external-html';

Examples

This content would be in a file called 'external_page.html'
<div id="consent">
  <p>
    This is a demo experiment, with this minimal consent form being loaded
    as an external html document. To continue, click the checkbox below
    and hit "Start Experiment".
  </p>
  <p>
    <input type="checkbox" id="consent_checkbox" />
    I agree to take part in this study.
  </p>
  <button type="button" id="start">Start Experiment</button>
</div>
jsPsych code to load above page.
// sample function that might be used to check if a participant has given
// consent to participate.
var check_consent = function(elem) {
    if (document.getElementById('consent_checkbox').checked) {
        return true;
    }
    else {
        alert("If you wish to participate, you must check the box next to the statement 'I agree to participate in this study.'");
        return false;
    }
    return false;
};

// declare the block.
var trial = {
    type: jsPsychExternalHtml,
    url: "external_page.html",
    cont_btn: "start",
    check_fn: check_consent
};

Open demo in new tab