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.
When you clone the experiments repo to create your branch, you'll get a folder that looks like this.
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
The template experiment you copied contains two files:
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>
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>
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: '',});
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 modevar 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.
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 experimentvar 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 locallyChildLangLabTrialData('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 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 experimentjsPsych.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 deployjsPsych.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.
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:
Different study conditions are given as .yaml files.
{include call to load yaml and how it gets set}/
Usually you want to add instructions; we use the jsPsych instructions plugin.
// instructionsvar 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:
// instructionsvar instructions = {type: 'instructions',pages: PARAMS.instructions.pages,show_clickable_nav: true}
Exposure phase.
Rating test option.
2AFC test.
Questionnaire demo
To test your changes locally, see that section of our create experiment protocol.
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.