Gorilla and jsPsych


Using your jsPsych task within a Gorilla experiment has never been easier. If you have existing tasks written in jsPsych, or already use it for building your own tasks, this guide will show you how simple it is to use your jsPsych code in Gorilla.

This guide is up to date as of jsPsych v7.0.


Importing your jsPsych task


Importing your original jsPsych task into Gorilla can be done in 3 simple steps. You will need:

  • Your code! Either the contents of the main script tags in your HTML file or the contents of your separate JavaScript file.
  • Your stimuli.
  • The jsPsych files required for your task. At the least, this will be the main jsPsych.js file.
  • About 10 minutes of your time!

Step 1) Create a new jsPsych Code Editor task in Gorilla (1 min)

From inside your project in Gorilla, press Create and then select Code Editor Task. Give your task a name and hit create.

The Code Editor wizard will then ask you what kind of task you want to set up: Select jsPsych starter for whichever version of jsPsych you're using.

This template is preloaded with the basic script you'll need to get up and running.

NB: In the Code Editor you may see the error message "Accessors are only available when targeting ECMAScript 5 and higher". This error message is a known issue that we're hoping to fix in the future. However, they are just compiler complaints and everything should still work correctly! You can safely ignore this error message.

Take a look below at the Code snippet showing the basic integration:

import gorilla = require("gorilla/gorilla"); // Make sure to upload the jsPsych files you need to the resources tab. // This should include the main jsPsych.js, jsPsych.css and likely at least one plugin. // In this case, we use the jspsych-html-keyboard-response.js plugin file. const jsPsych = window['jsPsych']; gorilla.ready(function(){ const timeline = []; const hello_trial = { type: 'html-keyboard-response', stimulus: 'Hello world!' } timeline.push(hello_trial); jsPsych.init({ display_element: $('#gorilla')[0], timeline: timeline, on_data_update: function(data){ gorilla.metric(data); }, on_finish: function(){ gorilla.finish(); } }); })

Step 2) Add in your timeline (2-10 mins)

We've already set up the Gorilla and jsPsych code basics: importing the main Gorilla module, setting up the .ready function and a basic jsPsych.init function. Now you just need to populate your jsPsych timeline.

Not using the jsPsych timeline? The timeline is a really intuitive system for building your experiment from basic blocks that was introduced in jsPsych 5. You can learn more about it here: https://www.jspsych.org/overview/timeline/

We've already created a timeline variable for you and assigned it in the jsPsych initialisation function. All you need to do is push the trials you require to it. In most cases, this will be as simple as copy pasting your existing code.

/* create timeline */ const timeline = []; /* define welcome message trial */ const welcome = { type: "html-keyboard-response", stimulus: "Welcome to the experiment. Press any key to begin." }; timeline.push(welcome); /* define instructions trial */ const instructions = { type: "html-keyboard-response", stimulus: "

In this experiment, a circle will appear in the center " + "of the screen.

If the circle is blue, " + "press the letter F on the keyboard as fast as you can.

" + "

If the circle is orange, press the letter J " + "as fast as you can.

" + "
"+ "
" + "

Press the F key

" + "
" + "

Press the J key

" + "
"+ "

Press any key to begin.

", post_trial_gap: 2000 }; timeline.push(instructions); /*ADD rest of your timeline here*/

Step 3) Add the jsPsych files you need (1 min)

These can all be uploaded in the Resources tab of the toolbox on the left hand side.

Make sure you also add script tag references to them in the Head tab. We've done this part automatically for some of the basic files that most tasks will use

And that's pretty much all there is to it! We've already linked the data collection to Gorilla and the end of the Task with Gorilla's own finish function.

To learn more about how to import your jsPsych Task into the Gorilla Code Editor check out our 'Hello_World' Tutorial here.


Is your task a little more involved?


Depending on how your task works and the additional features it requires, you may need to do a few more things to get everything working fully with Gorilla.

Add in stimuli

In jsPsych, you usually need to provide the file address of your stimuli. For example, 'img/image1.png'. In Gorilla, you'll need to replace this with the URL Gorilla provides that links to where your image is stored.

The first step is to upload all of your stimuli to the stimuli tab. Then, you can retrieve the URL for the stimuli using the command gorilla.stimuliURL('myImage.png'): this would retrieve the URL for the image 'myImage.png'.

We also recommend that you take advantage of jsPsych's image preloading functionality - this will download all of the stimuli your task requires so that they can be instantly accessed during the task. You can see an example of how to implement this in our jsPsych Tutorial Task 'Simple Reaction Time Task'.

//Adding in Stimuli // URL's for Blue and Orange images: const blueURL = gorilla.stimuliURL('blue.png'); const orangeURL = gorilla.stimuliURL('orange.png'); // We also create an array containing all the URL's for our required stimuli. // This is an important step which will be discussed further below! const images = []; images.push(blueURL); images.push(orangeURL); //Using the URLs Example: /* define instructions trial */ const instructions = { type: "html-keyboard-response", stimulus: "

In this experiment, a circle will appear in the center " + "of the screen.

If the circle is blue, " + "press the letter F on the keyboard as fast as you can.

" + "

If the circle is orange, press the letter J " + "as fast as you can.

" + "
"+ "
" + "

Press the F key

" + "
" + "

Press the J key

" + "
"+ "

Press any key to begin.

", post_trial_gap: 2000 }; timeline.push(instructions); /* start the experiment */ jsPsych.init({ display_element: $('#gorilla')[0], timeline: timeline, preload_images: images, show_preload_progress_bar: false, on_data_update: function(data){ gorilla.metric(data); }, on_finish: function() { jsPsych.data.displayData(); } });

Add additional metrics

By default, we've included some of the metrics that jsPsych generates. You can see these in the Metrics tab.

Gorilla Code Editor - Metrics Tab: Image below shows the default metrics available in the jsPsych Starter Project.

If you need to include more than this, you'll need to add new entries to the metrics tab. This way, Gorilla will know it needs to store them and you can assign an easily identifiable column name.


Don't already have a Gorilla account? Sign up now and get started building your jsPsych task today!