This document is a quick guide to start prototyping online experiments. Targeted at people with some programming knowledge but little to no experience with programming for the web.
which simplifies the process of designing an online behavioral experiment a lot. I can only emphasize that you go to the main website for documentation, it’s exhaustive and well written, but it assumes some knowledge of the web ecosystem. The goal of this document is rather to provide the high level, overview of what it even means to program for the web.
The web, or what you’ll need to start to learn
Here’s how the web works, roughly: a bunch of files sit on a server computer, somewhere you’ve likely never seen. When someone reaches for an web address, some magic process happens which connects that person’s computer and the server and things start to unfold. There are different type of files, and you’ll need to learn a few of them in order to understand what’s happening next. Here is a brief description of possible cases:
- HTML files. While those are central to a web page, most of the work being done by jsPsych means that you don’t have to learn too much about them. They are text files that have extra information to tell what each piece of text is. No programming is involved here per se: they describe stuff more than they compute anything. It usually looks like this:
<this-thing-is-a-title>Awesome Title</this-thing-is-a-title>, only less verbose.
- CSS files. Those tell the browser what various things should look like (think text size, colors, positions, ets.), but usually hold little content or computations. If you need animations though, this is probably where you’ll want to look.
PHPfiles. Those are responsible for whatever computation happens on the server computer. In particular they’ll have to handle saving data, and maybe choosing which files to present to a visitor.
In order to get into more details you can find here the skeleton of an experiment that has most of the useful ingredients, which you can try it here. Let’s break it downWhat happens when someone connects to the server to get the experiement? A rough description of the five steps that take place whenever an experiment runs. While the computation is done on the participant computer, a server is required to send the files and retrieve the data.
skeleton ├── index.php ├── done.html ├── exp.html ├── external-consent.html ├── script.js ├── instruction-text.js └── resources ├── my-style.css ├── save-data.php ├── save-data.js └── jspsych ├── jspsych.js ├── license.txt ├── css │ └── jspsych.css ├── my-plugins │ └── jspsych-survey-dropdown.js └── plugins ├── ... └── template └── jspsych-plugin-template.js
You can see two
php files, three
hmtl files, two
css files, and a bunch of
When I share an experiment to the world, I give them a link to that page. Since it runs computations on the server it can compute how many participants took the task so far and act accordingly, or maybe it can randomly assign participants to various conditions.
index.php usually does is to check whether the experiment is still running (for example by checking the number of participants who already took it), and then either sends the browser
done.html if no more participants are required, or serves
done.html is pretty straightforward, you can look at it to see a minimal HTML file but I won’t say much about it.
On the other hand
exp.html is a pretty uncommon HTML file. It looks like this:
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>experiment</title> <!-- js stuff --> <script src="resources/jspsych/jspsych.js"></script> <script src="..."></script> ... <!-- css stuff --> <link rel="stylesheet" href="resources/jspsych/css/jspsych.css"></link> <link rel="stylesheet" href="..."></link> ... <link rel="stylesheet" href="script.js"></link> </head> </html>
So really it loads a bunch of external files and that’s it. The reason for that is that in our case,
jsPsych is doing the heavy lifting: it dynamically creates a page for you, sets up a bunch of variables and timers, and allow you to handle the page entirely from the
js side — you’ll note that indeed the first thing it loads is the jspsych root file
jspsych.js. Order matters, here: earlier file get loaded and executed first. Typically the order is: main
jspsych.js file, then plugins, then style, then your main script, that I call in the exemple
jsPsych experiment script looks like this:
In this file you define the various blocks that are the different parts of your experiment, and you ask
jsPsych to start the experiment for you.
What you put in
type:'...' depends on the jsPsych plugin you want to run. Let’s say you want to write a bloc containing the instructions: you’re in luck, there’s a plugin for that whose doc is here. So you check out the documentation and you come up with the following block, for example:
Since text are quickly long, and you may want to avoid cluttering your files with too much text, you can keep the block definition in the
script.js file but put the text in a dedicated file: this is the purpose of my
instruction-text.js that only contains the definition of the variables setting the text for the instructions. The cost of breaking things into smaller files is often vastly compensated by the fact that the cleaner the code, the easier it is to check, share, read, debug, etc. Note that if you do so, you need to modify your
html file to include this new
js file before you use the variables: remember, files are loaded and executed in the order in which they appear in the
This means that you need to change your
exp.html accordingly to source the new file before the main one, in a manner similar to this:
While you may be perfectly happy with the default style that ships with jsPsych, one often need to finely tune some things to match the expectations of the experiments. This is done in the css file. Typically a
CSS file looks like this:
Which the browser roughly understands as this:
- Every element whose nature is to be a
paragraph should have text justified, of a given font size and no more than this many pixels wide.
- Every element that’s tagged to be of type
consentshould be written in green on red (please don’t do .that).
- The element uniquely identified as
consentshould be written in green on red.
p refers to an html element
<p>This is a paragraph</p>, the
#consent refers to an html element whose
consent such as
<div class='consent'>This is an online [...]</div> and finally the
.consent refers to an html element uniquely identified as
consent, such as
<input id='consent' type='button" value="I consent">
What about the other files?
Retrieving the data
save-data.php. If you run things on a computer you control, jsPsych has a thing meant to help you.
At NeuroSpin, we’ve setup a system to receive the files from the participants computer to an intranet-synced computer, more on the wiki at some point.
I chose to present the consent as a distinct page which was agreed upon. This is loaded through yet another plugin,
What is this
I didn’t write jsPsych, but those who did decided to publish it with a corresponding license to tell you what rights and duty you have with regard to the intellectual property of those who came up with the system. They mention it on the website here but it states pretty clearly that one can do a lot of thing with it provided:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
So, I can’t put the skeleton online without a copy of the license, which I happily do since it gives credit back to the original authors!
How to start playing with this
While most browsers will happily read files from your hard drive, it won’t really reproduce the behaviour you’d get online. Ultimately you’ll need a server on which you can put your files, a server that understands php files and has a public facing domain name such as
blog.s-m.ac/using-jspsych, but while you’re just testing and learning it’s a bit overkill.
Installing a full fledged server on your computer can be tedious and even dangerous if you don’t know what you’re doing, but luckily for you there’s a simple thing you can do. It won’t handle the PHP files but will be enough for
js: if you can access a console that has python available, you can go to the folder where your files are, and run either
Which will create a bare bone server for you, that you can open in your browser by going to the address http://127.0.0.1:8181/.
Useful tricks up your sleeves
The browser is outsmarting you …
Browsers are not always your friend. They will do whatever they can to optimize things: loading time, computations, etc. In that process they will produce seemingly unexpected behavior.
… but is such a great resource!
It provides awesome debugging/inspecting tools. You should notably learn to use the browser’s console: you open it by pressing
Ctrl+Maj+i, or maybe
F12. This is the browser giving you access to its internal representation of the code and the page. You can print the value of variables, see how your page is structured, etc.
And in particular, it gives you access to
console.log(): it outputs its argument(s) to the console. If you open your console you should see the result of the following piece of code written in the page:
Play around with the console, you can:
- Modify elements
- Print variables
- Inspect page, the memory, etc.
Among other things, you can simulate other setups and browsers: phones, touchscreens, limited connections, etc. Explore! Have fun!
Beware of “framework” answers
javscript is a programming language not everyone was happy with (you’ll quickly learn why). It has gotten better over time, but people created “frameworks” around it to make some operations easier to deal with, and a notable one is
jQuery. The reason I’m pointing this out is that
jsPsych does not assume you use any of these, but
stackoverflow.com often does.
Try to avoid
jQuery introduced new syntax: if an answers seems to use a lot of
$('...') it probably assumes you’re using
jQuery, which typically tou’re not
, look for
From the skeleton to an experiment