Creating a new plugin

Creating new plugins is the way to add new kinds of tasks to jsPsych. A task can be virtually any kind of activity. If it can be implemented in JavaScript, then it almost certainly can be turned into a plugin.

What's in a plugin file?

Plugin files follow a specific template. Adherence to the template is what allows jsPsych to run a plugin without knowing anything about what the plugin is doing. What makes plugins so flexible is that the template imposes very few requirements on the code. Here's what an empty plugin template looks like:

jsPsych['plugin-name'] = (function(){

  var plugin = {};

  plugin.create = function(params){
    var trials = [];

    trials.push({});

    return trials;
  }

  plugin.trial = function(display_element, trial){
    jsPsych.finishTrial();
  }

  return plugin;

})();

This plugin will work! It defines a plugin called 'plugin-name', and it does absolutely nothing. However, it won't break the experiment, and jsPsych will understand that this is a valid plugin.

Let's examine it in more detail.

The overall structure of the plugin is defined using a module JavaScript design pattern. In this pattern, we use what's called an anonymous closure. This is why the first line has (function(){ and the last line is })();. The details aren't important, but if you want to learn more about it, this is a nice overview. The reason this pattern is useful is because it allows for persistent state and private scope. In other words, the plugin is isolated can't be messed up by other plugins.

The module, created by the (function(){ })(); expressions, contains an object called plugin that has two properties, create and trial. Both properties define functions. The plugin object is returned at the end of the module, which is what assigns the defined properties of plugin to jsPsych['plugin-name'].

plugin.create

The create method is used during the initialization of the experiment. The purpose of the create method is to define an array of trial objects. Each trial object contains the parameters necessary for running a trial. A single trial object will be passed into the plugin.trial method as the trial parameter when the trial runs during the experiment. Therefore, any properties of the trial objects in the array can be accessed later on by the trial method while the experiment is running. The params parameter is the object created by an experimenter when they are defining an experiment. For example:

var block = {
  type: 'single-stim',
  stimuli: 'imgA.jpg',
  choices: ['A','B']
}

jsPsych.init({ experiment_structure: [block] });

The variable block will be passed into the create method of the single-stim plugin as the parameter params. The create method is then responsible for construction an array of trials with the appropriate set of parameters to run the trial.

plugin.trial

The trial method is responsible for running a single trial. There are two parameters that are passed into the trial method. The first, display_element, is the DOM element where jsPsych content is being rendered. The second, trial, is an object containing the parameters defined by the create method.

The only requirement for the trial method is that it calls jsPsych.finishTrial() when it is done. This is how jsPsych knows to advance to the next trial in the experiment (or end the experiment if it is the last trial). The plugin can do whatever it needs to do before that point.

Of course, there are other things that you will probably want the plugin to do besides just end. Here are some examples:

Change the content of the display

There are a few ways to change the content of the display. The display_element parameter of the trial method contains the jQuery representation of the DOM element for displaying content, so you can use various jQuery methods for manipulating the content. Two common ones are append and html.

display_element.append('<p>This is the first paragraph</p>');
display_element.append('<p>This is the second paragraph</p>');

append will add content to the display. The above calls would result in two paragraphs being rendered.

display_element.html('<p>This is the first paragraph</p>`);
display_element.html('<p>This paragraph will replace the first one</p>`);

html will replace the content on the display. The above calls will result in only the second paragraph appearing on the screen. It is often appropriate to use the html method to clear the display at the end of a trial:

// clear the display
display_element.html('');

Write data

Plugins exist to collect data, so saving data is obviously a crucial thing to do! There is a method to make this process easy:

jsPsych.data.write({
  correct: true,
  rt: 350
})

The above function call will record data for the trial. The data recorded will be that correct is true and that rt is 350. Additional data for the trial will also be collected automatically by the jsPsych library.

A plugin should only write data once per trial.

5.1 KiB Raw Blame History