Version: next

Adapt pre written code to run it in JATOS

Make your existing code run in JATOS - or how to jatosify a study

You might have a task, experiment, survey, or study running in a browser. You might have all its files like HTML, JavaScripts, images, etc. And now you want to run it with JATOS? Then follow this page.

Development 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: click Studies in JATOS header -> click "+" -> click New Study. Choose a study title and click Add. JATOS will have created a new folder within your assets root folder (default is the study's UUID and the location in /path_to_your_JATOS/study_assets_root/).
Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.
Back in the JATOS GUI, and within the newly created study, create a new component by clicking New Component. Choose a title and set the HTML file name, to the name of the HTML file you just copied into the study folder.
In your HTML, CSS and JavaScripts, for your paths you can choose between 1) relative paths or 2) absolute paths. Relative paths are recommended since they are shorter and do not change after an export-import of a study.
1. 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
```
<script src="survey.js"></script>
```
  E.g. or if the file is in a subfolder 'lib'
```
<script src="lib/survey.js"></script>
```
2. 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'
```
<script src="/study_assets/my-exp/survey.js"></script>
```
  ✰ For absolute paths make sure you understand the difference between the study_assets_root folder and the placeholder study_assets in your path names. study_assets_root is 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.

Edit your HTML and JavaScript

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
```
<script src="jatos.js"></script>`
```
Add jatos.onLoad
Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.
```
jatos.onLoad(function() {
  // start your code here 
});
```
Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. We can pass this function any data in text format including JSON, CSV or XML. If you pass a JavaScript object it will be turned into JSON (stringified).
E.g. if we want to send a JavaScript object as JSON
```
jatos.submitResultData(myResultDataObject);
```
jatos.submitResultData puts 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 jatos.appendResultData.
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:
```
jatos.startNextComponent();
```
Or to just finish the study:
```
jatos.endStudy();
```
You can combine this with sending result data:
```
jatos.startNextComponent(myResultDataObject);
```
or
```
jatos.endStudy(myResultDataObject);
```

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.
Use the study input or component input, defined in the study or component properties. With them you can change variables of your code directly through JATOS' GUI, which might come handy if someone isn't good in JavaScript.
You can add a quit button to your study to allow the participant to abort at any time.

Create the study in your local JATOS​

Edit your HTML and JavaScript​

Beyond the basics​

Create the study in your local JATOS

Edit your HTML and JavaScript

Beyond the basics