Merge pull request #3440 from jspsych/update-docs

v8 doc revision + expanding tutorials and `ParameterType` docs

Author: jodeleeuw

README.md

@@ -25,7 +25,7 @@ You can learn more about setting up a project by following the [hello world tuto
 
 Once you've got a project set up, the [reaction time task tutorial](https://www.jspsych.org/latest/tutorials/rt-task/) is a great next step, since it covers many core topics and features. 
 
-There are also a number of [video tutorials](https://www.jspsych.org/latest/tutorials/video-tutorials) available on the website.
+There are also a number of [community tutorials](https://www.jspsych.org/latest/tutorials/community-tutorials) available on the website.
 
 ## Examples
 

contributors.md

@@ -3,11 +3,15 @@ The following people have contributed to the development of jsPsych by writing c
 * Antonia - https://github.com/Ahoidal
 * aucuparia - https://github.com/aucuparia
 * Xiaolu Bai - https://github.com/lbai001
+* Niranjan Baskaran - https://github.com/Bankminer78
+* brchristian - https://github.com/brchristian
 * bjoluc - https://github.com/bjoluc
 * Christian Brickhouse - https://github.com/chrisbrickhouse
 * Teon L Brooks - https://github.com/teonbrooks
+* Susan Buck - https://github.com/susanBuck
 * Eamon Caddigan - https://github.com/eamoncaddigan
 * Jason Carpenter
+* Cherrie Chang - https://github.com/cherriechang
 * Steve Chao - https://github.com/stchao
 * Zhanwen "Phil" Chen - https://github.com/zhanwenchen
 * cthorey - https://github.com/cthorey
@@ -20,15 +24,17 @@ The following people have contributed to the development of jsPsych by writing c
 * Becky Gilbert - https://github.com/becky-gilbert
 * Mark Gorenstein - https://github.com/mgorenstein
 * Rui Han - https://github.com/hrcn
+* Eitan Hemed - https://github.com/EitanHemed
 * Andy Heusser - https://github.com/andrewheusser
 * Angus Hughes - https://github.com/awhug
-* jadeddelta - https://github.com/jadeddelta
+* jade - https://github.com/jadeddelta
 * Gustavo Juantorena - https://github.com/GEJ1
 * Chris Jungerius - https://github.com/cjungerius
 * George Kachergis - https://github.com/kachergis
 * Yul Kang - https://github.com/yulkang
 * Spencer King - https://github.com/spencerking
 * Jana Klaus - https://github.com/janakl4us
+* Ethan Knights - https://github.com/ethanknights
 * Arnold Kochari - https://github.com/akochari
 * Peter Jes Kohler - https://github.com/pjkohler 
 * kupiqu - https://github.com/kupiqu
@@ -38,6 +44,7 @@ The following people have contributed to the development of jsPsych by writing c
 * madebyafox - https://github.com/madebyafox
 * Shane Martin - https://github.com/shamrt
 * Vijay Marupudi - https://github.com/vijaymarupudi
+* Cian Monnin - https://github.com/CMonnin
 * Adrian Oesch - https://github.com/adrianoesch
 * Benjamin Ooghe-Tabanou - https://github.com/boogheta
 * Nikolay B Petrov - https://github.com/nikbpetrov
@@ -64,4 +71,5 @@ The following people have contributed to the development of jsPsych by writing c
 * Reto Wyss - https://github.com/retowyss
 * Shaobin Jiang - https://github.com/Shaobin-Jiang
 * Haotian Tu - https://github.com/thtTNT
-* Joshua Unrau - https://github.com/joshunrau
+* Joshua Unrau - https://github.com/joshunrau
+* Victor Zhang - https://github.com/vzhang03

docs/developers/extension-development.md

@@ -66,7 +66,7 @@ let trial = {
   extensions: [
     {type: myAwesomeExtension, params: {demo: 'value'}}
   ]
-});
+};
 
 //... extension code ...//
 class MyAwesomeExtension {
@@ -91,7 +91,7 @@ let trial = {
   extensions: [
     {type: myAwesomeExtension, params: {demo: 'value'}}
   ]
-});
+};
 
 //... extension code ...//
 class MyAwesomeExtension {
@@ -122,7 +122,7 @@ let trial = {
   on_finish: (data) => {
     console.log(data.awesome); // will output 'value'.
   }
-});
+};
 
 //... extension code ...//
 class MyAwesomeExtension {
@@ -168,9 +168,11 @@ The `version` field describes the version of the extension used and then durin t
 
 The `data` field is an object containing all of the `data` generated for the plugin. Each 'data' object has a `type` and `default` property. Additionally, this should be only used for data you choose to generate. Any jsdoc (comments included in the /** */ tags) you include will be scraped as metadata if you are choosing to generate metadata. This scraped metadata will also be used to create the JsPsych documentation.
 
+For more information on the various types of parameters one can include in their data field, see our [documentation on `ParameterType`s](./plugin-development.md#parameter-types).
+
 ### Optional methods
 
-The extension can also include any additional methods that are necessary for interacting with it. See the [webgazer extension](../extensions/webgazer.md) for an example.
+The extension can also include any additional methods that are necessary for interacting with it. See the [WebGazer extension](../extensions/webgazer.md) for an example.
 
 ## Advice for writing extensions
 

docs/developers/plugin-development.md

@@ -63,6 +63,10 @@ const info = {
 }
 ```
 
+??? info "Automatic versioning with custom build environments"
+
+    If you are using a custom build environment that imports its own `tsconfig.json` file that does not extend jsPsych's, and you want to use this automatic versioning syntax, you must add `"resolveJsonModule": true` to the config's `compilerOptions` object.
+
 If you are not using a build environment that supports `import` and `package.json` (such as writing a plain JS file), you can manually enter the `version` as a string.
 
 ```javascript
@@ -165,6 +169,89 @@ class MyAwesomePlugin {
 MyAwesomePlugin.info = info;
 ```
 
+#### Parameter Types
+
+jsPsych currently has support for the following parameter types:
+
+| Type Name | Description | Example |
+| --------- | ----------- | ------- |
+| BOOL | A simple truth value. | `true` or `false` |
+| STRING | A set of characters. | "Continue" |
+| INT | A value that supports whole numbers. | 12 |
+| FLOAT | A value that supports decimal numbers. | 5.55 |
+| FUNCTION | A Javascript function, tends to process multiple objects in an array from other parameters. | `function(tries) { return "<p>You have " + tries + " tries left." }` |
+| KEY | A single key, with support for function keys like arrows and spacebars. | `"j"`, `"n"`, `"ArrowLeft"` |
+| KEYS | Either an array of keys, or the string `"ALL_KEYS"` or `"NO_KEYS"`, indicating their respective inclusion/exclusion criterea. | `["f", "j"]` |
+| SELECT | A list of strings that a developer can choose between as a parameter. | `["cm", "px", "em"]` |
+| HTML_STRING | A string with HTML markup. | `"<p>This is the prompt.</p>"` |
+| IMAGE | A string that contains the path to an image file. | `"my_image.jpg"` |
+| AUDIO | A string that contains the path to an audio file. | `"my_sound.mp3"` |
+| VIDEO | A string that contains the path to a video file. | `"my_video.mp4"` |
+| OBJECT | A general JSON object (key-value pairs). | `{ rt: 350, response: "hello!", correct: true }` |
+| COMPLEX | A JSON object that one can specify nested parameters for. | `{ rt: 350, response: "hello!", correct: true }` |
+| TIMELINE | A jsPsych timeline object with trials. | `[{ type: jsPsychKeyboardResponse, stimulus: 'my_image.jpg }]` |
+
+Within each parameter, you may also specify if it is an array of the specific type. For example, a parameter that requires a list of button labels would be described as:
+
+```js
+const info = {
+  // ...
+  parameters: {
+    /** The labels to be displayed on each button. */
+    labels: {
+      type: ParameterType.STRING,
+      array: true,
+      default: ["Pause", "Play", "Continue"]
+    }
+  },
+  // ...
+}
+```
+
+Specific parameter types also have their own special markup. For `ParameterType.SELECT`, you specify the options one can choose with an `options` field, and then the `default` field must be within that field.
+
+```js
+const info = {
+  // ...
+  parameters: {
+    /** The units of measure used to display the length and width of the stimulus. */
+    units: {
+      type: ParameterType.SELECT,
+      options: ["em", "px", "vh", "vw"],
+      default: "px"
+    }
+  },
+  // ...
+}
+```
+
+For `ParameterType.COMPLEX`, we may specify the underlying fields in the object with the `nested` field. This acts in the same way as us defining parameters regularly, only we are now just delineating the fields within the object itself.
+
+```js
+const info = {
+  // ...
+  parameters: {
+    /** Where to display the location of the stimuli. */
+    locations: {
+      type: ParameterType.COMPLEX,
+      array: true,
+      default: undefined,
+      nested: {
+        /** The x-coordinate of the stimulus, in the units from the `units` field. */
+        x: {
+          type: ParameterType.INT
+        },
+        /** The y-coordinate of the stimulus. */
+        y: {
+          type: ParameterType.INT
+        }
+      }
+    }
+  },
+  // ...
+}
+```
+
 ## Plugin functionality
 
 Inside the `.trial()` method you can do pretty much anything that you want, including modifying the DOM, setting up event listeners, and making asynchronous requests. In this section we'll highlight a few common things that you might want to do as examples.

docs/overview/browser-device-support.md

@@ -22,11 +22,12 @@ There are many other web browsers that are available, but that are not commonly
 In general, jsPsych experiments can be run on mobile devices (smartphones and tablets). However, certain plugins will not work on mobile. For instance, any plugin that requires a keyboard response without a text input box, such as the *-keyboard-response plugins, will not work. Even plugins that do work on mobile might work differently than they do on desktop and laptop computers. For instance, on mobile devices, a text input box will cause an on-screen keyboard to pop up, which affects the visible content on the screen.
 
 If you plan to run an experiment that allows people to use mobile devices, we recommend doing some extra testing to make sure that everything works as expected. In particular, you may want to check that:
-* Font sizes are readable on smaller screens
-* Stimuli sizes are large enough and appropriate for the task
-* Page is laid out as intended (e.g. elements are centered and do not overlap)
-* Response options are touchscreen-friendly (e.g. buttons rather than key presses)
-* Response options (e.g. buttons, text boxes, radio buttons) are large enough and far enough apart to be easily selected with a finger tap
+
+ * Font sizes are readable on smaller screens
+ * Stimuli sizes are large enough and appropriate for the task
+ * Page is laid out as intended (e.g. elements are centered and do not overlap)
+ * Response options are touchscreen-friendly (e.g. buttons rather than key presses)
+ * Response options (e.g. buttons, text boxes, radio buttons) are large enough and far enough apart to be easily selected with a finger tap
 
 It's possible to use your browser's developer tools to emulate mobile devices ([this page shows how to do it in Chrome](https://developers.google.com/web/tools/chrome-devtools/device-mode)), which is useful for getting a sense of how your experiment will look on mobile devices. Just be aware that there are limitations to emulator tools, and there are some aspects of mobile devices/browsers that a desktop browser will not be able to simulate.
 

docs/overview/building-surveys.md

@@ -387,7 +387,7 @@ Rather than repeating a question format within the same trial, perhaps you want
               elements: [
                 {
                   type: "text", 
-                  title: `Enter a word related to ${jsPsych.timelineVariable('word').toUpperCase()}:`, 
+                  title: `Enter a word related to ${jsPsych.evaluteTimelineVariable('word').toUpperCase()}:`, 
                   autocomplete: "off" 
                 }
               ], 
@@ -416,7 +416,7 @@ Rather than repeating a question format within the same trial, perhaps you want
       // Create question using timeline variables
       const page = survey.addNewPage('page1');
       const question = page.addNewQuestion('text'); 
-      question.title = `Enter a word related to ${jsPsych.timelineVariable('word').toUpperCase()}`;
+      question.title = `Enter a word related to ${jsPsych.evaluateTimelineVariable('word').toUpperCase()}`;
       question.autocomplete = "off";
       // Set survey-level parameters
       survey.showQuestionNumbers = false;

docs/overview/extensions.md

@@ -1,6 +1,6 @@
 # Extensions
 
-Extensions are jsPsych modules that can interface with any plugin to extend the functionality of the plugin. A canonical example of an extension is eye tracking. An eye tracking extension allows a plugin to gather gaze data and add it to the plugin's data object.
+In jsPsych, extensions allow one to extend the functionality of various plugins, giving individual plugins the ability to collect more data, display additional stimuli, and more. A canonical example of an extension is [eye tracking](../extensions/webgazer.md), which allow plugins to gather gaze data and add it to the their respective data objects. For a full list of extensions directly included in the jsPsych release, see [here](../extensions/list-of-extensions.md).
 
 ## Using an Extension
 
@@ -16,7 +16,7 @@ To use an extension in an experiment, you'll load the extension file via a `<scr
 ```js
 initJsPsych({
   extensions: [
-    {type: jsPsychExtensionExample, params: {...} }
+    { type: jsPsychExtensionExample, params: {...} }
   ]
 })
 ```
@@ -26,17 +26,11 @@ To enable an extension during a trial, add the extension to the `extensions` lis
 ```js
 var trial = {
   extensions: [
-    {type: jsPsychExtensionExample, params: {...} }
+    { type: jsPsychExtensionExample, params: {...} }
   ]
 }
 ```
 
-## List of Extensions
-
-Extension | Description
------- | -----------
-[jspsych&#8209;ext&#8209;webgazer.js](../extensions/webgazer.md) | Enables eye tracking using the [WebGazer](https://webgazer.cs.brown.edu/) library.
-
 ## Writing an Extension
 
 See our [developer's guide for extensions](../developers/extension-development.md) for information about how to create a new extension.

docs/overview/media-preloading.md

@@ -3,7 +3,7 @@
 If an experiment uses image, audio, or video files as stimuli, it is a good idea to preload the files before running the experiment. You can preload files at any point in your experiment using the [jsPsych `preload` plugin](../plugins/preload.md). Preloading files means that the participant's browser will download the files and store them in local memory on the participant's computer. This is important because displaying or playing a media file is much faster if it is already in memory on the participant's computer. Without preloading, there will be noticeable delays in the display of media, which will affect any timing measurements (such as how long an image is displayed, or a participant's response time since first viewing an image). For particularly large files, like video, preloading content avoids lengthy pauses in the middle of the experiment that can be disruptive to the flow of the experiment.
 
 !!! warning
-		Note that video preloading will not work when you run your experiment offline (e.g., by double-clicking on the HTML file), but it will work once your experiment is running online (hosted on a server). The [Cross-origin requests (CORS) and safe mode](running-experiments.md#cross-origin-requests-cors-and-safe-mode) section on the Running Experiments page contains more information about this.
+	Note that video preloading will not work when you run your experiment offline (e.g., by double-clicking on the HTML file), but it will work once your experiment is running online (hosted on a server). The [Cross-origin requests (CORS) and safe mode](running-experiments.md#cross-origin-requests-cors-and-safe-mode) section on the Running Experiments page contains more information about this.
 
 ## Automatic Preloading
 

docs/plugins/audio-slider-response.md

@@ -28,6 +28,7 @@ In addition to the [parameters available in all plugins](../overview/plugins.md#
 | prompt                         | string           | null          | This string can contain HTML markup. Any content here will be displayed below the stimulus. The intention is that it can be used to provide a reminder about the action the participant is supposed to take (e.g., which key to press). |
 | trial_duration                 | numeric          | null          | How long to wait for the participant to make a response before ending the trial in milliseconds. If the participant fails to make a response before this timer is reached, the participant's response will be recorded as null for the trial and the trial will end. If the value of this parameter is null, then the trial will wait for a response indefinitely. |
 | response_ends_trial            | boolean          | true          | If true, then the trial will end whenever the participant makes a response (assuming they make their response before the cutoff specified by the `trial_duration` parameter). If false, then the trial will continue until the value for `trial_duration` is reached. You can set this parameter to `false` to force the participant to listen to the stimulus for a fixed amount of time, even if they respond before the time is complete. |
+| trial_ends_after_audio         | boolean          | false         | If true, then the trial will end as soon as the audio file finishes playing. |
 | response_allowed_while_playing | boolean          | true          | If true, then responses are allowed while the audio is playing. If false, then the audio must finish playing before the slider is enabled and the trial can end via the next button click. Once the audio has played all the way through, the slider is enabled and a response is allowed (including while the audio is being re-played via on-screen playback controls). |
 
 ## Data Generated

docs/plugins/initialize-camera.md

@@ -18,7 +18,7 @@ In addition to the [parameters available in all plugins](../overview/plugins.md#
 Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
 device_select_message | html string | `<p>Please select the camera you would like to use.</p>` | The message to display when the user is presented with a dropdown list of available devices.
-button_label | sting | 'Use this camera.' | The label for the select button.
+button_label | string | 'Use this camera.' | The label for the select button.
 include_audio | bool | false | Set to `true` to include an audio track in the recordings.
 width | int | null | Request a specific width for the recording. This is not a guarantee that this width will be used, as it depends on the capabilities of the participant's device. Learn more about `MediaRecorder` constraints [here](https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API/Constraints#requesting_a_specific_value_for_a_setting).
 height | int | null | Request a specific height for the recording. This is not a guarantee that this height will be used, as it depends on the capabilities of the participant's device. Learn more about `MediaRecorder` constraints [here](https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API/Constraints#requesting_a_specific_value_for_a_setting).

docs/plugins/initialize-microphone.md

@@ -18,7 +18,7 @@ In addition to the [parameters available in all plugins](../overview/plugins.md#
 Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
 device_select_message | html string | `<p>Please select the microphone you would like to use.</p>` | The message to display when the user is presented with a dropdown list of available devices.
-button_label | sting | 'Use this microphone.' | The label for the select button.
+button_label | string | 'Use this microphone.' | The label for the select button.
 
 
 ## Data Generated