
.. _PsychoJS: https://github.com/psychopy/psychojs

.. _onlineHowWorks:

How does it work?
--------------------------

The first stage of this is that there is now a JavaScript library, `PsychoJS`_, that mirrors the PsychoPy Python library classes and functions.

PsychoPy Builder is effectively just writing a script for you based on the visual representation of your study so the new feature is for it simply to write a html/JavaScript/PsychoJS page instead.

Modern browsers are remarkably powerful. Most browsers released since 2011 have allowed HTML5 which supports more flexible rendering of web pages (images and text can be positioned precisely enough to run "proper" behavioural experiments). Since 2013 most have supported WebGL. That allows graphics to be rendered really quickly using "hardware acceleration" on your graphics card. The result is rich pages that can be updated very rapidly and can be forced to sync to screen refresh, which is critical for stimulus timing.

All this means we can do great things with online experiments that actually have good temporal precision!

The way it works is that you have a web page containing JavaScript (generated by PsychoPy Builder). You upload that to a web server. The participant of your study uses their web browser to visit the page you've created with a standard URL you send them.

Now, JavaScript executes on their computer (as opposed to scripts like PHP that operate on the server and aren't directly visible to the viewer/browser). In this case the PsychoJS script will present a dialog box at the start of the study to get the participant ID and any other basic information you need. While that dialog box is presented the script will be downloading all your stimuli and files to the local computer and storing them in memory. When all the necessary files are downloaded the participant can press "OK" and the experiment will start.

The experiment supports all the standard timing aspects of any PsychoPy Builder experiment; you can specify your stimuli in terms of time presented or number of screen refreshes etc (and the actual refresh rate of your participant's computer will be stored in your data file). When it's finished it saves the data into a comma-separated-value (CSV) file in the "data" folder on the web server. This looks very much like the standard CSV outputs of your same PsychoPy experiment run locally.

Not all components are currently supported. Keep an eye on the :ref:`onlineStatus` page to see what objects you can use already.

How does this compare with jsPsych?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The PsychoPy team doesn't don't know much about the underlying technology of `jsPsych <http://docs.jspsych.org/>`_ (e.g. its timing of stimuli and use of advanced graphics like WebGL) but one notable difference is the additional flexibility that PsychoPy provides in terms of creating your trials. In jsPsych you use one of the pre-programmed "types" of trial (like single stimulus or 2-alternative-forced-choice) and you have rather little flexibility over how that gets conducted. If you wanted to alter the positioning of the stimuli, for instance, in a 2-alternative-force-choice task or you wanted a stimulus to change in time (appear gradually or move location) then you would need to write a new trial "type" using raw javascript.

PsychoPy, by comparison, is designed to give you total flexibility. You decide what constitutes a "trial" and how things should operate in time. We think that control is very important to creating a wide range of studies.

Also, of course, there's no Builder interface for jsPsych as far as we know, so you'll need to know how to program in JavaScript.
