Program your experiment

How to program an experiment with jsPsych
Prerequisites
This page describes how to make changes to the lab's experiment template. If you haven't already, make sure you start by reading the create experiments protocol.
Create experiment protocol
/protocols/create-experiments
The experiments repo
When you clone the experiments repo to create your branch, you'll get a folder that looks like this. 
Experiments repo
Here's what's in there:
archive: a folder for completed experiments
assets: a folder for css, js, images, and consents we all need
expX : a bunch of folders called expX (e.g. exp21), these are running experiments
template: the experiment template (you'll make a copy of this to work from!)
.gitignore: tells git to ignore some files we don't want to track
README.md: the README file for the repo
childlanglab.js: javascript functions to send JSON data to php
write_participants.php: writes to our participants table
write_run.php: writes to our runs table
update_run.php : updates a run with the study data
You'll copy the template folder and make modifications there. Changes made anywhere else will cause your pull request to be rejected
Start from the template
The template experiment you copied contains two files: 
template experiment in experiments repo
The run-exp.html file started out like this:
<!DOCTYPE html>
<html>
  <!-- libraries and stylesheets go in the header -->
  <head>
    <title>ChildLangLab Experiment X</title>
  </head>
​
  <!-- the body this is where the experiment gets displayed -->
  <body></body>
​
  <!-- the javascript that runs the experiment -->
  <script></script>
</html>
Required head material
In the <head>, we added the basic libraries and stylesheets you'll need to build an experiment in the lab. You should change the X in the <title> to your experiment's exp_id.
run-exp-v1.html
<!DOCTYPE html>
<html>
  <head>
    <title>ChildLangLab Experiment X</title>
​
    <!-- libraries required for jsPsych plugins -->
    <script src="../assets/js/jspsych-6.0.5/jspsych.js"></script>
    <script src="../assets/js/jspsych-6.0.5/plugins/jspsych-fullscreen.js"></script>
    <script src="../assets/js/jspsych-6.0.5/plugins/jspsych-instructions.js"></script>
​
    <!-- library required for writing to our database -->
    <script src="../childlanglab.js"></script>
​
    <!-- libraries required for YAML parsing -->
    <script src="../assets/js/yaml.js" type="text/javascript"></script>
​
    <!-- stylesheets for making everything pretty -->
    <link href="../assets/js/jspsych-6.0.5/css/jspsych.css" rel="stylesheet" type="text/css"></link>
    <link href="../assets/css/childlanglab.css" rel="stylesheet" type="text/css"></link>
   
  </head>
  
  <!-- the body this is where the experiment gets displayed -->
  <body></body>
​
  <!-- the javascript that runs the experiment -->
  <script></script>
</html>
Required javascript
addProperties
Our database requires you to include the following fields in every experiment, so we've added these properties to the template. This function adds these fields to every trial of your experiment.
jsPsych.data.addProperties(
    {
        random_id: '', 
        condition: '',
        exp_phase: '',
    }
);
labreq_start
The javascript that runs the experiment gets written in between <script></script> We've added the lab's required start screen for you. It makes the browser go fullscreen and runs ChildLangLabRuntime(), a function that write to our 'runs' table in our database. 
<script>
    // for writing runtime data and displaying in fullscreen mode
    var labreq_start = {
      type: 'fullscreen',
      fullscreen_mode: true,
      on_start: function(){
        ChildLangLabRuntime();
      }
    };
</script>
You should //comment out the ChildLangLabRuntime(); when testing locally, as only the lab's server has permission to insert rows into these database tables.
labreq_end
We've also included the lab's required end screen, which shows our logo and says "thanks" to the participant. It also writes out the trial-by-trial to the experiment's table in our database.
    // the thanks screen at the end of the experiment
    var labreq_end = {
      type: 'image-button-response',
      stimulus: '../assets/images/childlanglab-logo.png',
      choices: ['End Experiment'],
      prompt: "<p>Thanks for participating!</p>",
      on_start: function(){
        // ChildLangLabTrialData writes your trial data to the lab's database
        // comment this out when you test locally
        ChildLangLabTrialData('write_trialdata.php', jsPsych.data.get().json());
      }
    };
You should //comment out the ChildLangLabTrialData(); when testing locally, as only the lab's server has permission to insert rows into these database tables.
jsPsych.init
​jsPsych.init launches the experiment. Anything you want in the experiment has to be added to this timeline. You can see that we've included labreq_start and labreq_end. You'd include any additional blocks in between those.
  /* *************ADD YOUR EXTRA CODE HERE ********************* */
​
​
​
    /* *****************ADD YOUR BLOCKS TO THE EXPERIMENT ************* */
    // make sure you add your blocks and trials to the experiments timeline below
​
    // start the experiment
    jsPsych.init({
      timeline: [labreq_start, /* add here */ labreq_end],
      on_finish: function(){
        // jsPsych.data.displayData() shows your data on the final screen
        // comment this out when you deploy
        jsPsych.data.displayData();
      }
    })
​jsPsych.data.displayData() is a helper function that shows all of the data you collected in your experiment on the final screen. You need this to check that you are saving the data you think you are.
Add your experiment code
Consent form
If you are running an experiment on prolific, you'll need to display our consent form and request consent via a checkbox. Add the following code to show the lab's consent form:
​
Conditions
Different study conditions are given as .yaml files.
{include call to load yaml and how it gets set}/
Instructions
Usually you want to add instructions; we use the jsPsych instructions plugin. 
// instructions
var instructions = {
  type: 'instructions',
  pages: [
    "First page of instructions",
    "Second page of instructions",
    "Third page of instructions"
  ],
  show_clickable_nav: true
}
If you need to change instructions based on conditions, you could set the instructions in the conditions .yaml file:
instructions:
  pages:
    - "This is the first page"
    - "This is the second page"
    - "This is the third page"
and do this in run-exp.html instead:
// instructions
  var instructions = {
    type: 'instructions',
    pages: PARAMS.instructions.pages,
    show_clickable_nav: true
  }
Exposure 
Exposure phase.
Rating test
Rating test option.
2AFC test
2AFC test.
Questionnaire
Questionnaire demo
Update the experiment timeline
Update the timeline
Turn on preloading 
Update the on_finish function
Test locally
To test your changes locally, see that section of our create experiment protocol.
On the server
Experiments are hosted on our experiment server: http://experiments.childlanglab.com/. Visit the Run Experiment tab to run your experiment. If you'll be offsite, make sure you bring the lab's wifi hotspot — you need an internet connection.
​
​