Migrating an experiment to v7.x

The release of version 7.0 changes a number of core components of jsPsych. We made these changes to improve jsPsych's compatibility with modern JavaScript tools like package managers and bundlers and to improve the developer experience for people contributing to jsPsych's codebase. We hope these changes will improve the long-term viability of the project and encourage more developers to contribute to jsPsych.

Our aim was to accomplish these goals with minimal changes to the user experience of jsPsych. However, we did have to change a few critical things. This guide is aimed at users who are familiar with v6.x of jsPsych and would like to understand what's changed in v7.x.

Loading jsPsych

There are now three different ways you can load jsPsych into your HTML file. We've updated the hello world tutorial to walk through each of the three options. If you are looking for the option that is most similar to the version 6.x experience, check out option 2. The biggest difference from what you are used to is that the directory structure of the downloaded library is slightly different and plugin files are named a little bit differently.

Initializing and running jsPsych

We've removed jsPsych.init() and split the features into two different functions.

At the start of your experiment script, you'll now call initJsPsych() to get a new instance of jsPsych. This is where you will pass in the variety of parameters that used to go into jsPsych.init(), with the exception of the timeline parameter.

var jsPsych = initJsPsych({
  use_webaudio: false,
  on_finish: function(){
    jsPsych.data.displayData();
  }
});

Once you've created your timeline, then you'll launch the experiment by calling jsPsych.run(), passing in the timeline as the only argument.

var timeline = [...]

jsPsych.run(timeline);

The `type` parameter for trials

The type parameter now expects the value to be a plugin class rather than a string.

For example, if you load the html-keyboard-response plugin from the CDN...

<script src="http://unpkg.com/@jspsych/plugin-html-keyboard-response@1.0.0"></script>

... or from the plugin-html-keyboard-response.js file in the release archive...

<script src="plugin-html-keyboard-response.js"></script>

... then a global variable defining the plugin's class called jsPsychHtmlKeyboardResponse is available.

To create a trial using the plugin, pass this class as the type parameter. Note that the value is not a string.

var trial = {
  type: jsPsychHtmlKeyboardResponse,
  stimulus: 'Hello, version 7.0!'
}

Using extensions

Like plugins, extensions are now also referenced by their class. Extensions are initiliazed in initJsPsych() instead of jsPsych.init().

var jsPsych = initJsPsych({
  extensions: [
    {type: jsPsychExtensionWebgazer}
  ]
})

The class is also used in trials that use the extension.

var trial = {
  type: jsPsychHtmlKeyboardResponse,
  stimulus: 'Hello, version 7.0!',
  extensions: [
    {type: jsPsychExtensionWebgazer}
  ]
}

Custom plugins

If you have custom plugins that you would like to upgrade to be compatible with v7.x we recommend using our plugin template.

The new template implements plugins as a class, but the core components are essentially unchanged.

Anything in plugin.info from a v6.x plugin should be moved into the info object. Note that the type argument for the parameters follows a slightly different syntax in the v7.x plugins. This object is then assigned as a static property of the class.
Anything in plugin.trial from a v6.x plugin should be moved into the trial method inside the class.
The new template has a constructor() function that accepts an instance of jsPsych. You do not need to adjust this portion of the plugin.

There are a few changes to be aware of that may affect your code.

We removed the registerPreload function and we now auto-detect media to preload via the type argument specified in the info object. If a parameter is listed as IMAGE, AUDIO, or VIDEO, it will be automatically preloaded. If you wish to disable preloading you can set the preload flag to false for the parameter.
If you invoke any functions from jsPsych, like jsPsych.finishTrial(), note that jsPsych is no longer a global variable and you must use the reference to jsPsych that is passed to the constructor. To do this, simple prefix all jsPsych references with this., e.g., jsPsych.finishTrial() becomes this.jsPsych.finishTrial().

Need help?

If you encounter issues migrating code to v7.x, feel free to post in our support thread for migration.

5.0 KiB Raw Blame History