Make Your Existing Code Run in JATOS - or How To Jatosify a Study
Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow
Create the study in your local JATOS
Create a new study with the 'New Study' button in JATOS' header. Choose a study title and a folder name. Leave the other fields empty for now and click 'Create'. JATOS will have created a new folder within your assets root folder (default is
Back in the JATOS GUI, and within the newly created study, create a new component by clicking 'Components' and then 'New'. Choose a component title and set the HTML file name, to the name of the HTML file you just copied into the study folder.
Relative paths) Just use the relative path within your study's folder.
E.g. if a file named 'survey.js' is in the root of the study's assets folder
E.g. or if the file is in a subfolder 'lib'
Absolute paths (deprecated)) Always use the prefix
/study_assets/and then the study assets name you specified in your study's properties when you created it.
E.g. if you want to load the file 'survey.js' and the study's assets folder is 'my-exp'
✰ For absolute paths make sure you understand the difference between the
study_assets_rootfolder and the placeholder
study_assetsin your path names.
study_assets_rootis the folder in your system (or in the server) where the assets (HTML, JS, CSS, images, etc) of all your JATOS studies will be stored. You can configure the location of this folder.
study_assets, on the other hand, is just a placeholder that will go in your HTML files. JATOS will interpret this and replace the placeholder with the path, (specific to the study) that you entered in the field 'Study assets directory name' in your Study's Properties. The advantage of this is that you can change the location or name of the assets for any study, or export-import a study into a different computer, and the study will still run without having to make any changes in the HTML code.
- Now it's time for a first glimpse: Click the 'Run' button in either the study's or the component's toolbar. Your experiment should run like it did before without JATOS. Use the browser's developer tools to check for eventually missing files and other occurring errors.
Up to this point JATOS served as a mere provider of your files. Now we want to use a feature of JATOS: We want to store your result data in JATOS' safe database.
Include the jatos.js library in your HTML. In your
<head>add the line
Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.
// start your code here
Now to actually send your result data to JATOS we use jatos.js' function
jatos.submitResultDataputs the data into JATOS database - old data that were submitted before will be overwritten. If you don't want to overwrite data you should rather use
Instead of submitting text you can also upload files with jatos.uploadResultFile.
At the end of your component you will want to jump to another component or end the study.
To jump to the next component:
Or to just finish the study:
You can combine this with sending result data:
That's about it. Infos about other jatos.js functions and variables you can find in the reference.
Beyond the basics
- Think about dividing your study into several components. You could have separate components e.g. for introduction, training, experiment and feedback. You could even consider splitting the experiment into several parts. One advantage is that if your participant stops in the middle of your study you still have the result data of the first components. Also, you can re-use components in different studies.
- You can add a quit button to your study to allow the participant to abort at any time.