diff --git a/docs/developers/plugin-development.md b/docs/developers/plugin-development.md index 1cede3f713..ac098be9e5 100644 --- a/docs/developers/plugin-development.md +++ b/docs/developers/plugin-development.md @@ -31,7 +31,7 @@ The plugin's `trial()` method is responsible for running a single trial. When th There are three parameters that are passed into the trial method. * `display_element` is the DOM element where jsPsych content is being rendered. This parameter will be an `HTMLElement`, and you can use it to modify the portion of the document that jsPsych controls. -* `trial` is an object containing all of the parameters specified in the corresponding [TimelineNode](../overview/timeline). +* `trial` is an object containing all of the parameters specified in the corresponding [TimelineNode](../overview/timeline.md). * `on_load` is an optional parameter that contains a callback function to invoke when `trial()` has completed its initial loading. See [handling the on_load event](#asynchronous-loading). The only requirement for the `trial` method is that it calls `jsPsych.finishTrial()` when it is done. This is how jsPsych knows to advance to the next trial in the experiment (or end the experiment if it is the last trial). The plugin can do whatever it needs to do before that point. @@ -168,7 +168,7 @@ trial(display_element, trial){ ### Asynchronous loading -One of the [trial events](../overview/events) is `on_load`, which is normally triggered automatically when the `.trial()` method returns. In most cases, this return happens after the plugin has done its initial setup of the DOM (e.g., rendering an image, setting up event listeners and timers, etc.). However, in some cases a plugin may implement an asynchronous operation that needs to complete before the initial loading of the plugin is considered done. An example of this is the `audio-keyboard-response` plugin, in which the check to see if the audio file is loaded is asynchronous and the `.trial()` method returns before the audio file has been initialized and the display updated. +One of the [trial events](../overview/events.md) is `on_load`, which is normally triggered automatically when the `.trial()` method returns. In most cases, this return happens after the plugin has done its initial setup of the DOM (e.g., rendering an image, setting up event listeners and timers, etc.). However, in some cases a plugin may implement an asynchronous operation that needs to complete before the initial loading of the plugin is considered done. An example of this is the `audio-keyboard-response` plugin, in which the check to see if the audio file is loaded is asynchronous and the `.trial()` method returns before the audio file has been initialized and the display updated. If you would like to manually trigger the `on_load` event for a plugin, the `.trial()` method accepts an optional third parameter that is a callback function to invoke when loading is complete. diff --git a/docs/index.md b/docs/index.md index 23f7a80ce5..15a1f6eba7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,10 +4,10 @@ jsPsych is a JavaScript framework for creating behavioral experiments that run in a web browser. -Experiments in jsPsych are created using [plugins](overview/plugins). +Experiments in jsPsych are created using [plugins](overview/plugins.md). Each plugin defines different kinds of events, like showing an image on the screen, and collects different kinds of data, like recording which key was pressed at which time. -You can use the plugins that are [included with jsPsych](plugins/list-of-plugins), use plugins that are developed by community members in the [contrib repository](https://github.com/jspsych/jspsych-contrib), or [create your own plugins](developers/plugin-development/). -By assembling different plugins together into [a timeline](overview/timeline), it is possible to create a wide range of experiments. +You can use the plugins that are [included with jsPsych](plugins/list-of-plugins.md), use plugins that are developed by community members in the [contrib repository](https://github.com/jspsych/jspsych-contrib), or [create your own plugins](developers/plugin-development.md). +By assembling different plugins together into [a timeline](overview/timeline.md), it is possible to create a wide range of experiments. [The page on timelines](overview/timeline.md) is a good place to start learning about jsPsych. From there, you might want to complete the [hello world tutorial](tutorials/hello-world.md) to learn how to set up a jsPsych experiment and the [reaction time experiment tutorial](tutorials/rt-task.md) to learn the core features of the framework. diff --git a/docs/overview/experiment-options.md b/docs/overview/experiment-options.md index 70b3e396b6..ea58409605 100644 --- a/docs/overview/experiment-options.md +++ b/docs/overview/experiment-options.md @@ -128,7 +128,7 @@ initJsPsych({ ## Add extensions -[Extensions](extensions/) are jsPsych modules that can run throughout the experiment and interface with any plugin to extend the functionality of the plugin. One example of an extension is eye tracking, which allows you to gather gaze data during any trial and add it to that trial's data object. If you want to use extensions in your experiment, you must specify this when you initialize the experiment with `initJsPsych`. The `extensions` parameter in `initJsPsych` is an array of objects, where each object specifies the extension that you'd like to use in the experiment. Below is an example of adding the webgazer extension. +[Extensions](extensions.md) are jsPsych modules that can run throughout the experiment and interface with any plugin to extend the functionality of the plugin. One example of an extension is eye tracking, which allows you to gather gaze data during any trial and add it to that trial's data object. If you want to use extensions in your experiment, you must specify this when you initialize the experiment with `initJsPsych`. The `extensions` parameter in `initJsPsych` is an array of objects, where each object specifies the extension that you'd like to use in the experiment. Below is an example of adding the webgazer extension. ```js initJsPsych({ diff --git a/docs/overview/plugins.md b/docs/overview/plugins.md index b091329e80..3c3376adf6 100644 --- a/docs/overview/plugins.md +++ b/docs/overview/plugins.md @@ -1,11 +1,11 @@ # Plugins In jsPsych, plugins define the kinds of trials or events that should occur during the experiment. -Some plugins define very general events, like [displaying a set of instructions pages](../plugins/instructions/), [displaying an image and recording a keyboard response](../plugins/image-keyboard-response/), or [playing a sound file and recording a button response](../plugins/audio-button-response/). -Other plugins are more specific, like those that display particular kinds of stimuli (e.g., a [circular visual search array](../plugins/visual-search-circle/)), or run a specific version of particular kind of task (e.g., the [Implicit Association Test](../plugins/iat-image/)). +Some plugins define very general events, like [displaying a set of instructions pages](../plugins/instructions.md), [displaying an image and recording a keyboard response](../plugins/image-keyboard-response.md), or [playing a sound file and recording a button response](../plugins/audio-button-response.md). +Other plugins are more specific, like those that display particular kinds of stimuli (e.g., a [circular visual search array](../plugins/visual-search-circle.md)), or run a specific version of particular kind of task (e.g., the [Implicit Association Test](../plugins/iat-image.md)). Part of creating an experiment with jsPsych involves figuring out which plugins are needed to create the tasks you want your participants to perform. -Plugins provide a structure for a particular trial or task, but often allow for significant customization and flexibility. For example, the [image-keyboard-response plugin](../plugins/image-keyboard-response/) defines a simple structure for showing an image and collecting a keyboard response. You can specify the what the stimulus is, what keys the participant is allowed to press, how long the stimulus should be on the screen, how long the participant has to respond, and so on. Many of these options have reasonable default values; even though the image plugin has many different parameters, you only *need* to specify the image stimulus in order to use it. Each plugin has its own documentation page, which describes what the plugin does, what options are available, and what kind of data it collects. +Plugins provide a structure for a particular trial or task, but often allow for significant customization and flexibility. For example, the [image-keyboard-response plugin](../plugins/image-keyboard-response.md) defines a simple structure for showing an image and collecting a keyboard response. You can specify the what the stimulus is, what keys the participant is allowed to press, how long the stimulus should be on the screen, how long the participant has to respond, and so on. Many of these options have reasonable default values; even though the image plugin has many different parameters, you only *need* to specify the image stimulus in order to use it. Each plugin has its own documentation page, which describes what the plugin does, what options are available, and what kind of data it collects. ## Using a plugin diff --git a/docs/overview/style.md b/docs/overview/style.md index 52bfaf05f8..fb74500a1e 100644 --- a/docs/overview/style.md +++ b/docs/overview/style.md @@ -17,7 +17,7 @@ const trial = { } ``` -You can also use a [dynamic parameter](dynamic-parameters) to combine inline CSS and trial-specific variables. This allows you to easily apply the same inline CSS to multiple trials. Here's an example using a dynamic stimulus parameter and [timeline variables](timeline.md#timeline-variables): +You can also use a [dynamic parameter](dynamic-parameters.md) to combine inline CSS and trial-specific variables. This allows you to easily apply the same inline CSS to multiple trials. Here's an example using a dynamic stimulus parameter and [timeline variables](timeline.md#timeline-variables): ```javascript const trial = { @@ -157,7 +157,7 @@ const fixation = { ``` -You may want the `css_classes` parameter to vary across trials. If so, you can turn it into a [dynamic parameter](dynamic-parameters) or use [timeline variables](timeline.md#timeline-variables) (see examples below). +You may want the `css_classes` parameter to vary across trials. If so, you can turn it into a [dynamic parameter](dynamic-parameters.md) or use [timeline variables](timeline.md#timeline-variables) (see examples below). One thing to note about the `css_classes` parameter is that it only adds the class(es) to the jspsych-content <div> element, which is the "parent" element that contains all of the experiment content. Often you'll want your CSS rules to be applied to other elements _inside_ of this jspsych-content div. Sometimes your CSS rules will be "inherited" by all of the other jsPsych content inside of this parent <div>. For instance, in the `fixation` example above, the CSS rules that change the font size, weight and color are applied to the parent <div> and automatically passed on to the stimulus text through inheritance. diff --git a/docs/overview/timeline.md b/docs/overview/timeline.md index b168c3c219..7177843836 100644 --- a/docs/overview/timeline.md +++ b/docs/overview/timeline.md @@ -4,7 +4,7 @@ To create an experiment using jsPsych, you need to specify a timeline that descr ## A single trial -To create a trial, you need to create an object that describes the trial. The most important feature of this object is the `type` parameter. This tells jsPsych which plugin to use to run the trial. For example, if you want to use the [html-keyboard-response plugin](../plugins/html-keyboard-response) to display a short message, the trial object would look like this: +To create a trial, you need to create an object that describes the trial. The most important feature of this object is the `type` parameter. This tells jsPsych which plugin to use to run the trial. For example, if you want to use the [html-keyboard-response plugin](../plugins/html-keyboard-response.md) to display a short message, the trial object would look like this: ```javascript const trial = { @@ -55,7 +55,7 @@ timeline.push(trial_3); ## Nested timelines -Each object on the timeline can also have its own timeline. This is useful for many reasons. One is that it allows you to define common parameters across trials once and have them apply to all the trials on the nested timeline. The example below creates a series of trials using the [image-keyboard-response plugin](../plugins/image-keyboard-response/), where the only thing that changes from trial-to-trial is the image file being displayed on the screen. +Each object on the timeline can also have its own timeline. This is useful for many reasons. One is that it allows you to define common parameters across trials once and have them apply to all the trials on the nested timeline. The example below creates a series of trials using the [image-keyboard-response plugin](../plugins/image-keyboard-response.md), where the only thing that changes from trial-to-trial is the image file being displayed on the screen. ```javascript const judgment_trials = { diff --git a/docs/plugins/list-of-plugins.md b/docs/plugins/list-of-plugins.md index 24fd55debc..4bfbedd6b4 100644 --- a/docs/plugins/list-of-plugins.md +++ b/docs/plugins/list-of-plugins.md @@ -15,12 +15,12 @@ Plugin | Description [browser‑check](browser-check.md) | Measures various features of the participant's browser and runs an inclusion check to see if the browser meets a custom set of criteria for running the study. [call‑function](call-function.md) | Executes an arbitrary function call. Doesn't display anything to the participant, and the participant is usually unaware that this plugin has even executed. It's useful for performing tasks at specified times in the experiment, such as saving data. [canvas‑button‑response](canvas-button-response.md) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and record a button click response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). -[canvas‑keyboard‑response](canvas-keyboard-response) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). +[canvas‑keyboard‑response](canvas-keyboard-response.md) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). [canvas‑slider‑response](canvas-slider-response.md) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and ask the participant to respond by moving a slider to indicate a value. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). [categorize‑animation](categorize-animation.md) | The participant responds to an animation and can be given feedback about their response. [categorize‑html](categorize-html.md) | The participant responds to an HTML-formatted stimulus using the keyboard and can be given feedback about the correctness of their response. [categorize‑image](categorize-image.md) | The participant responds to an image using the keyboard and can be given feedback about the correctness of their response. -[cloze](cloze) | Plugin for displaying a cloze test and checking participants answers against a correct solution. +[cloze](cloze.md) | Plugin for displaying a cloze test and checking participants answers against a correct solution. [external‑html](external-html.md) | Displays an external HTML page (such as a consent form) and lets the participant respond by clicking a button or pressing a key. Plugin can validate their response, which is useful for making sure that a participant has granted consent before starting the experiment. [free‑sort](free-sort.md) | Displays a set of images on the screen in random locations. Participants can click and drag the images to move them around the screen. Records all the moves made by the participant, so the sequence of moves can be recovered from the data. [fullscreen](fullscreen.md) | Toggles the experiment in and out of fullscreen mode. diff --git a/docs/plugins/preload.md b/docs/plugins/preload.md index 4a676d2fc9..aa548cd35e 100644 --- a/docs/plugins/preload.md +++ b/docs/plugins/preload.md @@ -2,7 +2,7 @@ Current version: 1.1.3. [See version history](https://github.com/jspsych/jsPsych/blob/main/packages/plugin-preload/CHANGELOG.md). -This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow. We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large and/or many media files. See the [Media Preloading page](../overview/media-preloading/) for more information. +This plugin loads images, audio, and video files. It is used for loading files into the browser's memory before they are needed in the experiment, in order to improve stimulus and response timing, and avoid disruption to the experiment flow. We recommend using this plugin anytime you are loading media files, and especially when your experiment requires large and/or many media files. See the [Media Preloading page](../overview/media-preloading.md) for more information. The preload trial will end as soon as all files have loaded successfully. The trial will end or stop with an error message when one of these two scenarios occurs (whichever comes first): (a) all files have not finished loading when the `max_load_time` duration is reached, or (b) all file requests have responded with either a load or fail event, and one or more files has failed to load. The `continue_after_error` parameter determines whether the trial will stop with an error message or end (allowing the experiment to continue) when preloading is not successful. @@ -15,7 +15,7 @@ All other parameters can be left unspecified if the default value is acceptable. | Parameter | Type | Default Value | Description | | --------------------- | -------------- | -------------------------------- | ---------------------------------------- | | auto_preload | boolean | false | If `true`, the plugin will preload any files that can be automatically preloaded based on the main experiment timeline that is passed to `jsPsych.run`. If `false`, any file(s) to be preloaded should be specified by passing a timeline array to the `trials` parameter and/or an array of file paths to the `images`, `audio`, and/or `video` parameters. Setting this parameter to `false` is useful when you plan to preload your files in smaller batches throughout the experiment. | -| trials | timeline array | [] | An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to automatically preload stimuli files from a specific subset of the experiment. See [Creating an Experiment: The Timeline](../overview/timeline) for information on constructing timelines. | +| trials | timeline array | [] | An array containing one or more jsPsych trial or timeline objects. This parameter is useful when you want to automatically preload stimuli files from a specific subset of the experiment. See [Creating an Experiment: The Timeline](../overview/timeline.md) for information on constructing timelines. | | images | array | [] | Array containing file paths for one or more image files to preload. This option is typically used for image files that can't be automatically preloaded from the timeline. | | audio | array | [] | Array containing file paths for one or more audio files to preload. This option is typically used for audio files that can't be automatically preloaded from the timeline. | | video | array | [] | Array containing file paths for one or more video files to preload. This option is typically used for video files that can't be automatically preloaded from the timeline. | @@ -223,4 +223,4 @@ import preload from '@jspsych/plugin-preload'; Open demo in new tab -For more examples, see the `jspsych-preload.html` file in the `/examples` folder of the release and the [Media Preloading](../overview/media-preloading) documentation page. \ No newline at end of file +For more examples, see the `jspsych-preload.html` file in the `/examples` folder of the release and the [Media Preloading](../overview/media-preloading.md) documentation page. \ No newline at end of file diff --git a/docs/plugins/webgazer-calibrate.md b/docs/plugins/webgazer-calibrate.md index 1b64a138f7..78ad766550 100644 --- a/docs/plugins/webgazer-calibrate.md +++ b/docs/plugins/webgazer-calibrate.md @@ -25,7 +25,7 @@ In addition to the [default data collected by all plugins](../overview/plugins.m Name | Type | Value -----|------|------ -No data currently added by this plugin. Use the [webgazer-validate](../webgazer-validate) plugin to measure the precision and accuracy of calibration. +No data currently added by this plugin. Use the [webgazer-validate](webgazer-validate.md) plugin to measure the precision and accuracy of calibration. ## Simulation Mode diff --git a/docs/reference/jspsych.md b/docs/reference/jspsych.md index 2dc987efe1..65478b26a2 100644 --- a/docs/reference/jspsych.md +++ b/docs/reference/jspsych.md @@ -687,7 +687,7 @@ jsPsych.setProgressBar(0.85); ## jsPsych.timelineVariable ```javascript -jsPsych.timelineVariable(variable, call_immediate) +jsPsych.timelineVariable(variable) ``` ### Parameters diff --git a/docs/tutorials/hello-world.md b/docs/tutorials/hello-world.md index 3935ea82d4..ebc860e02c 100644 --- a/docs/tutorials/hello-world.md +++ b/docs/tutorials/hello-world.md @@ -147,7 +147,7 @@ Once the plugin is loaded we can create a trial using the plugin. To declare a t ### Step 5: Run the experiment -Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](../overview/timeline). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. +Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](../overview/timeline.md). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. ```html hl_lines="18" @@ -307,7 +307,7 @@ For this demo we want to show some text on the screen. This is exactly what the ``` -Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the `html-keyboard-response` plugin, we create an object with the property `type` equal to `jsPsychHtmlKeyboardResponse`. We can specify the other parameters of the plugin in the same object. Here we use the `stimulus` parameter to include a message. You can see the full set of parameters for each plugin on its [documentation page](../plugins/html-keyboard-response). +Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the `html-keyboard-response` plugin, we create an object with the property `type` equal to `jsPsychHtmlKeyboardResponse`. We can specify the other parameters of the plugin in the same object. Here we use the `stimulus` parameter to include a message. You can see the full set of parameters for each plugin on its [documentation page](../plugins/html-keyboard-response.md). ```html hl_lines="13 14 15 16" @@ -332,7 +332,7 @@ Once the plugin is loaded we can create a trial using the plugin. To declare a t ### Step 7: Run the experiment -Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](../overview/timeline). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. +Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](../overview/timeline.md). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. ```html hl_lines="18" @@ -429,7 +429,7 @@ const trial = { ### Step 6: Run -Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](../overview/timeline). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. +Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](../overview/timeline.md). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. ```js import {initJsPsych} from 'jspsych';