add extension docs

docs/extensions/extensions.md

@@ -16,7 +16,9 @@ To use an extension in an experiment, you'll load the extension file via a `<scr
 ```js
 jsPsych.init({
   timeline: [...],
-  extensions: ['some-extension']
+  extensions: [
+    {type: 'some-extension', params: {...}
+  ]
 })
 ```
 
@@ -36,7 +38,7 @@ Extension | Description
 
 ## Writing an Extension
 
-To create a new extension you must create an object that supports a few event callbacks. A barebones extension file might look like this:
+To create a new extension you must create an object that supports a few event callbacks. A barebones extension file looks like this:
 
 ```js
 jsPsych.extensions['new-extension'] = (function () {
@@ -56,8 +58,23 @@ jsPsych.extensions['new-extension'] = (function () {
   }
 
   extension.on_finish = function(){
-
+    return {
+      // any data that the extension will add to a trial
+    }
   }
   
+  return extension;
 });
-```
+```
+
+The four events that an extension must support are shown in the sample code.
+
+`extension.initialize` is called with `jsPsych.init()`. This is where setup code for the extension can happen. This event will happen once per experiment, unlike the other events which occur with each trial. The `params` object can include whatever parameters are necessary to configure the extension. The params object is passed from the call to `jsPsych.init()` to the `extension.initialize` method. This method must return a `Promise` that resolves when the extension is finished initializing. 
+
+`extension.on_start` is called at the start of the plugin execution, prior to calling `plugin.trial`. This is where trial-specific initialization can happen, such as creating empty containers to hold data or resetting internal state.
+
+`extension.on_load` is called after `plugin.trial` has executed, which is typically when the plugin has finished executing initial DOM-modifying code and has set up various event listeners. This is where the extension can begin actively interacting with the DOM and recording data.
+
+`extension.on_finish` is called after the plugin completes. This can be used for any teardown at the end of the trial. This method should return an object of data to append to the plugin's data. Note that this event fires *before* the `on_finish` event for the plugin, so data added by the extension is accessible in any trial `on_finish` event handlers.
+
+The extension can also include any additional methods that are necessary for interacting with it. See the [webgazer extension](/extensions/jspsych-ext-webgazer.md) for an example.

docs/extensions/jspsych-ext-webgazer.md

@@ -0,0 +1,83 @@
+# jspsych-ext-webgazer
+
+This extension supports eye tracking through the [WebGazer](https://webgazer.cs.brown.edu/) library. For a narrative description of how to use this extension see the [eye tracking overview](/overview/eye-tracking.md).
+
+## Parameters
+
+Parameters can be set when calling `jsPsych.init()`
+
+```js
+jsPsych.init({
+  extensions: [
+    {type: 'webgazer', params: {...}}
+  ]
+})
+```
+
+Parameter | Type | Default Value | Description
+----------|------|---------------|------------
+webgazer  | object | `undefined` | You can explicitly pass a reference to a loaded instance of the webgazer.js library. If no explicit reference is passed then the extension will look for a global `webgazer` object.
+
+## Data Generated
+
+Name | Type | Value
+-----|------|------
+webgazer_data | array | An array of objects containing gaze data for the trial. Each object has an `x`, a `y`, and a `t` property. The `x` and `y` properties specify the gaze location in pixels and `t` specifies the time in milliseconds since the start of the trial.
+
+## Functions
+
+### faceDetected()
+
+Returns `true` if WebGazer is ready to make predictions (`webgazer.getTracker().predictionReady` is `true`).
+
+### showPredictions()
+
+Turns on WebGazer's real-time visualization of predicted gaze location.
+
+### hidePredictions()
+
+Turns off WebGazer's real-time visualization of predicted gaze location.
+
+### showVideo()
+
+Turns on a display of the webcam image, guiding box for positioning the face, and WebGazer's estimate of the location of facial landmarks.
+
+### hideVideo()
+
+Turns off the camera display.
+
+### resume()
+
+Turns on gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with webgazer.
+
+### pause()
+
+Turns off gaze prediction. The extension will automatically handle this for you in most cases. You probably only need to use this if you are writing your own plugin that interfaces directly with webgazer.
+
+### stopMouseCalibration()
+
+Stops WebGazer from using mouse movements and mouse clicks as calibration events.
+
+### startMouseCalibration()
+
+Turns on mouse movement and mouse clicks as calibration events.
+
+### calibratePoint(x, y)
+
+Instructs WebGazer to register the location `x`, `y` (in screen pixel coordinates) as a calibration event. Can be used for passive viewing calibration, i.e., instructing participants to fixate at a particular location.
+
+### setRegressionType(regression_type)
+
+Change the method that WebGazer is using to perform feature -> location regression. Valid options are `ridge`, `weightedRidge`, and `threadedRidge`. See the WebGazer docs for more information about these options.
+The extension uses the default mode specified by WebGazer (currently `ridge`).
+
+### getCurrentPrediction()
+
+Get the current predicted gaze location from WebGazer. Returns an object with `x`, `y`, and `eyeFeature` properties. This function is asynchronus, so proper use requires either the `await` keyword in the context of another `async function` or using `.then()`. 
+
+```js
+jsPsych.extensions.webgazer.getCurrentPrediction().then(function(data){
+  console.log(`Currently looking at coordinate ${data.x}, ${data.y}`)
+});
+```
+

docs/overview/eye-tracking.md

@@ -19,7 +19,9 @@ To use the WebGazer extension in an experiment, include it in the list of extens
 ```js
 jsPsych.init({
   timeline: [...],
-  extensions: ['webgazer']
+  extensions: [
+    {type: 'webgazer'}
+  ]
 })
 ```
 

extensions/jspsych-ext-webgazer.js

@@ -127,8 +127,9 @@ jsPsych.extensions['webgazer'] = (function () {
     }
   }
 
-  extension.getCurrentPrediction = function () {
-    return state.webgazer.getCurrentPrediction();
+  extension.getCurrentPrediction = async function () {
+    var prediction = await state.webgazer.getCurrentPrediction();
+    return prediction;
   }
 
   // extension.addGazeDataUpdateListener(listener){