v6.2.0

Note from @jodeleeuw: 6.2 is our first release that is made possible by support from a grant by Mozilla Open Source Support (MOSS). This award has allowed @becky-gilbert to join the team, and she has been essential to all of the work reflected here. So: thanks Mozilla, and thanks @becky-gilbert!

New Features

• The instructions plugin now has a page_label parameter that allows you to change the default "Page" text when showing the page number/total. This provides better support for non-English languages. Thanks @GEJ1! (#1081, #1082)
• By default, the survey-* plugins now turn off the autocomplete/autofill feature, so that participants won't see a list of their previous responses in text entry fields. This feature can be turned back on with the new autocomplete parameter. Thanks @chrisbrickhouse! (#1064, #1073)
• The survey-html-form plugin now includes the autofocus parameter that allows you to specify the ID of the form field that you want the page to focus on when the trial loads. Thanks @chrisbrickhouse and @grocio! (#1072, #1062, #669, #671)
• In a survey-likert trial, you can now select a response by clicking on the label text. Thanks @kurokida! (#701)
• You can now set a minimum valid keyboard response time in your experiment using the new minimum_valid_rt parameter in jsPsych.init. This is useful for automatically ignoring key presses that are unreasonably fast. Thanks @andytwoods! (#1139, #546, #542)
• All audio-*/video-* plugins now include the response_allowed_while_playing parameter. If false, the participant will not be able to respond until the media has finished playing. Before then, keyboard responses will be ignored, and buttons/sliders will be visible but disabled. (#1137, #1145)
• New canvas-* plugins allow you to use a function to draw the stimulus on a HTML canvas element, and collect a keyboard, button, or slider response. A canvas stimulus can be useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). Thanks @cjungerius! (#700)
• New maxdiff plugin displays a set of options to be selected as one of two mutually-exclusive categories, typically 'most' or 'least' on some criteria, e.g. importance, preference, similarity. The same option cannot be selected for both categories simultaneously. Thanks @awhug! (#1136)
• The free-sort plugin now has new parameters to control: sort area shape (square or circle), initial item positioning (inside or outside the sort area), border/background colors indicating when items are in/out of the area, magnification of items while dragging, and text indicating whether and how many items are left to be placed inside. Thanks @pjkohler! (#1018, #1203)
• The image-*, animation, and categorize-animation plugins now include a render_on_canvas parameter to fix the problem with brief blank screens (white flashes) between consecutive images/trials in Firefox and Edge. Setting render_on_canvas to true fixes this problem, and setting it to false presents the image(s) in an img element, as before. (#891 #969, #1174)
• New documentation pages in the Overview section on the jsPsych website: Browser and Device Support and Running Experiments.
• New 'safe mode' feature automatically prevents CORS errors when running experiments offline (e.g. by double-clicking the HTML file). This can be overridden with the new override_safe_mode parameter in jsPsych.init. For more info about CORS errors and safe mode, see https://www.jspsych.org/overview/running-experiments/#offline.

Changes

• The *-slider-response plugins now automatically save the stimulus and slider start position in the data, and they return an integer rather than string as the response. Thanks @kupiqu! (#736, #689, #1058).
• In the *-slider-response plugins, the slider starting value parameter is now called slider_start (for consistency with video-slider-response plugin, where start refers to the video start time). The slider's starting value is now stored in the trial data, which is useful if the researcher is randomizing the slider's starting value. (#1060, #736)
• When require_movement is true in the *-slider-response plugins, the user will be allowed to continue after clicking on the cursor (rather than having to move the cursor and release it). This makes the sliders more user-friendly, especially when using a discrete/sparse scale, and when the participant wants to respond with the slider's starting position. Thanks @kupiqu! (#696)
• In the same-different-html and same-different-image plugins, the default values for first_stim_duration and second_stim_duration were changed from 1000 ms to null. This fixes a bug that prevented these parameters from being set to null. Thanks @dschreij! (#755)
• In all *-button-response plugins, the "button_pressed" data is now saved as an integer rather than a string, which is now consistent with the documentation. Thanks @vijaymarupudi! (#682)
• By default, the image-*, animation, and categorize-animation plugins now draw the images on a canvas element, to fix a problem with brief blank screens (white flashes) between consecutive images in Firefox and Edge. Setting render_on_canvas to false will present the image(s) in an img element, as in previous versions of these plugins. (#891 #969, #1174)
• In the video-* plugins, the parameter for specifying the video file(s) is now called stimulus rather than sources, for consistency with other plugins. (#1261, #1171)

Bug Fixes

• The rdk plugin now appropriately changes the fixation cross color based on the fixation_cross_color parameter. Thanks @cthorey and @lukasshannon! (#643 #1217)
• Incorrect error message no longer displayed when using jsPsych.randomization.shuffleNoRepeats() (#659)
• jsPsych.randomization.repeat() now fails gracefully when the items and repetitions parameters are ambiguous. Thanks @Hrcn ! (#667)
• The start and slider_start parameters now work as expected in the video-slider-response plugin. Thanks @vijaymarupudi! (#713, #714)
• The website's tutorials and the library's example HTML files no longer include the unnecessary closing link tag (</link>) after loading the default CSS file. Thanks @vijaymarupudi! (#721)
• The labels and radio buttons/checkboxes in survey-multi-choice and survey-multi-select plugins are now properly formatted. Thanks @dillonplunkett! (#676)
• We've fixed several documentation errors, such as out-of-date parameter names and broken links. Thanks @akochari, @CarolynBuck-Gengler, @dschreij, @alisdt, and @gorkang! (#677, #1096, #827, #755, #668, #1225)
• The rdk plugin no longer shows scroll bars on the page. Thanks @wsr017 and @vijaymarupudi! (#881, #787)
• jsPsych.addNodeToEndOfTimeline no longer produces an error when the optional callback function is omitted. Thanks @oliveralonzo, @bjmeagher, and @vijaymarupudi! (#688, #918, #690)
• Data collection .first and .last functions now handle the case where the n argument is greater than the total number of trials in the collection, and they throw a descriptive error when n is zero or negative. Thanks @aridyckovsky! (#976, #751)
• The image-button-response and image-keyboard-response plugins now produce a console warning when the trial might be deadlocked because a response does not end the trial (response_ends_trial: false) and no trial duration is set (trial_duration: null). Thanks @chrisbrickhouse and @celstark! (#1014, #1028)
• Incorrect error message "Uncaught TypeError: Cannot read property 'style' of null at update_loading_progress_bar" no longer displayed when playing HTML5 audio. (#648, #1115)
• Fixed out-of-date Github URLs in package.json file to improve npm install compatibility. Thanks @aridyckovsky! (#971)
• Added a more informative error message when the timeline parameter is empty in jsPsych.init() (#853)
• In the case of a timeline with a loop function nested inside a timeline with timeline variables, the timeline variables can now be referenced inside the loop function. (#664)
• The serial-response-time-mouse plugin now works properly when a prompt is added to the screen. Thanks @takat0-ch (#840, #837)
• Fixed a bug where an error was thrown if the Array.prototype had been extended and parameters with COMPLEX types were used in plugins. Thanks @egaudrain! (#989, #990)
• jsPsych.init() will now delay execution until the document is fully loaded (#948). This fixes an issue where jsPsych would create two sets of <body> tags on the document if none existed in the markup (#316). Thanks @bjoluc!
• Fixed bug on touchscreen-only devices (phones/tablets) that caused the last button that was touched to remain highlighted on successive *-button-response trials. (#977)
• The preloading progress bar correctly centers when the experiment_width property is set in jsPsych.init(). (#1160)
• For all video-* plugins in Firefox, if a non-zero video start time is specified, then the first frame of the video is no longer briefly visible when the trial first loads. (#712, #1162)
• Fixed alignment problems between slider positions and labels in all *-slider-response plugins. (#1193, #695)
• In the image-* plugins, the maintain_aspect_ratio parameter now works as intended: when only one image dimension is specified and maintain_aspect_ratio is false, the unspecified dimension will be the image's original dimension, and the image will stretch or compress accordingly. (#1174, #1172)
• Fixed a bug in video-* plugins that was preventing videos from automatically preloading. Thanks @mgorenstein! (#1171)
• Fixed a bug in audio-button-response that was producing an "undefined startTime" error. Thanks @esolitos! (#1194)
• The audio-button-response...

v6.1.0

New Features

• Added an option to specify an event handler for on_close in jsPsych.init(). This event is triggered when the user leaves the page. It can be used to save the data and/or state of the experiment just before the window is closed and the data is lost (#324).
• Added jsPsych.getProgressBarCompleted(), which returns the current value of the progress bar. Works for automated and manual control mode of the progress bar (#538).
• Video files will now preload. Thanks @andytwoods ! (#408, #535).
• The survey-text plugin now supports a required parameter. (#460).
• Individual data values in the data parameter can now be functions that are evaluated at the start of the trial (#562).
• Created three new plugins for video stimulus with different response options: video-keyboard-response, video-button-response, and video-slider-response. Thanks @designatednerd ! (#636; #622).
• The video plugins now supports setting the playback rate. Thanks @r-b-g-b ! (#590).
• Added cloze test plugin. Thanks @sprengholz ! (#555).
• A custom label can be specified for the automatic progress bar. Thanks @retowyss ! (#609).
• All survey plugins now support randomize_question_order parameter, which randomly reorders all questions (#305).
• The various image- plugins now allow for setting the height and width of the image by the parameters stimulus_height and stimulus_width. The parameter maintain_aspect_ratio can be used to automatically resize one dimension when specifying the other (#560).
• The slider plugins now support a parameter called require_movement. When set to true, the continue button is disabled until the slider has been moved (#573).
• The slider plugins now have a parameter called slider_width which can be used to set the width of the slider in pixels (#631).
• Added a new plugin that supports a more versatile set of html form elements, survey-html-form. Thanks @jansim ! (#602).
• Added jsPsych.randomization.shuffleAlternateGroups() which allows for shuffling based on a group membership, ensuring that items from each group are spaced evenly and in a consistent group order (#528).
• Added alternate-groups option to sampling methods for timeline variables (#528).
• Added a parameter to jsPsych.init to control the width of the experiment display, experiment_width (#635).
• The survey-likert plugin now has a parameter scale_width to specify the width of the likert scales in pixels (#633).
• All the survey plugins now support a name parameter in the questions array. This parameter controls the name of the response in the data, replacing the default of Q0, Q1, etc. (#608).

Changes

• Dropped support for Date.now() as a method for measuring RT. Browser support for performance.now() is now widespread (#492).
• .variance() and .sd() now calculate sample variance and standard deviation instead of population variance and standard deviation (#601).
• In nested timeline structures, data properties that do not conflict between a nested node and their parent node will now both be added to the data structure. Previously, only the nested node's data was added, even if the data properties were not in conflict (#391).
• Added more informative error messages for some functions in the randomization module (#389).
• The value parameter for the survey-text plugin has been replaced with placeholder and the text is now used as a proper placeholder attribute (#627).
• The survey-multi-select plugin required parameter is now specified at the question level to be consistent with other survey plugins. Proper HTML5 form validation is used to display the error message (#629).
• The jspsych-RDK plugin was renamed to jspsych-rdk to be consistent with other plugins. Thanks @vrsivananda ! (#630; #575).
• Various documentation improvements and updates (#607, #524).

Bug Fixes

• Div IDs were incorrectly generated in the survey-text plugin (#576).
• The survey-text plugin was reloading the page on form submission in Safari and Edge. Thanks @nabsul ! (#610; #613).
• The survey-text plugin has proper auto focus on the first input element (#580).
• Full screen event data is now properly recorded in recent versions of Firefox (#597).
• The loading progress bar should no longer be larger than expected (#603).
• Default values were not properly used when the plugin had a nested parameter (e.g., the questions parameter in the various survey-* plugins). Defaults are now used as expected (#628).
• The default_iti parameter in jsPsych.init() is working as intended (#632).

v6.0.5

New Features

• The call-function plugin can now wait for asynchronous functions to execute a callback before continuing to the next trial. (#552).
• The RDK plugin now accepts character codes for selecting keys (#564). Thanks @vrsivananda !
• The content element will automatically scroll to the top on a new trial, which fixes some issues where long surveys were stuck at the bottom of the page on a new trial.
• Default key behavior (like space causing the page to scroll) is now prevented when the key is expected as input for a plugin that uses getKeyboardResponse to capture input.

Bug Fixes

• The Open Sans font now correctly imports in the stylesheet. Thanks @guydav !
• In some cases the backwards button in the instructions plugin would not work properly. Thanks for reporting, @kushinm ! (#553)
• In some cases, image preloading would fail because values of null, 0, or false would be added to the list of images to load. (#557).
• A bug in the external-html plugin caused a keyboard event handler to persist when it should have been cleared. Thanks @tbrotherm !
• Two minor bugs were resolved in the RDK plugin (#565). Thanks @vrsivananda !
• The -slider-response plugins had the wrong parameter type for the labels parameter, causing issues in the GUI. (#571).
• Automatically putting the focus on the jsPsych content div was failing due to targeting the wrong element. (#563).

v6.0.4

New features

• Added plugin for Random Dot Kinematograms by @vrsivananda. Thanks for this major contribution!
• Added the ability to display page numbers in the instructions plugin. Thanks @mjaquiery!
• External scripts can now be optionally executed in the external-html plugin. Thanks @onkeltom!

Documentation updates

• The PHP script example in the documentation for saving files to a server is fixed for recent versions of PHP. Thanks @akochari!
• localSave() for data collections works in recent versions of Safari. Thanks @spencerking!
• Audio examples are updated to reflect the Chrome 66+ restrictions on playing audio. Thanks @mpezzo!

Bug fixes

• The free-sort plugin now properly records the final locations of the images.
• The instructions plugin handles custom key assignments when allow_backwards is false. Thanks @pfeyz!
• In some older browsers, the display element would lose focus when a button was clicked. By default, the display element is automatically focused at the start of every trial. Thanks @akochari!

v6.0.3

This update mainly addresses the Chrome 66+ audio autoplay issue. Briefly: Chrome 66+ no longer allows audio to autoplay until after the user has taken one action on the page. jsPsych creates the audio context when jspsych.js is loaded, and this is usually before the user takes an action. This updates modifies the way that jsPsych uses the audio context so that it is automatically unblocked after the first action that the user takes.

This update also modifies the survey-text plugin so that the first text field is auto focused.

v6.0.2

This release patches a few bugs in 6.0.1 and adds two small features.

New features

• If preloading content fails, jsPsych will retry each failed file up to a specified number of times. The default behavior is 10 attempts. This can be overriden by setting max_preload_attempts in jsPsych.init()
• Use of the WebAudio API is now optional. It can be disabled by setting use_webaudio in jsPsych.init() to false. HTML5 Audio is now automatically used as a backup when WebAudio is not available.

Bug fixes

• The survey-text plugin now works when rows and/or columns is unspecified. Thanks @VorontsovIE !
• jsPsych would attempt to create a new AudioContext on every jsPsych.init() call. This is now corrected and jsPsych uses a single AudioContext even if there are multiple inits on the same page.
• The start and stop options for jspsych-video now work in Microsoft Edge.
• The vertical scrollbar only appears if the experiment is too tall to fit in the window.
• Various errors in the documentation and tutorials were corrected. Thanks @hans and @yulkang !

v6.0.1

This update fixes a bug that occurred when trial parameters were set to null. For example, this code caused undesired behavior:

var trial = {
  type: 'html-keyboard-response',
  stimulus: 'oops.',
  post_trial_gap: null
}

v6.0

This is a major update to jsPsych that reflects more than 100 changes to the library. Given the scope of the update, this document focuses only on high-level changes to the library. Note that many of the changes to the library break backwards compatibility with any prior jsPsych version.

New features

• Timeline Variables are a powerful new tool for writing efficient code. They allow you to define parameters on a timeline that are replaced by variables. The variables can be grouped so that a value for one parameter is always paired with a value for another parameter. There are many new features built on top of the timeline variables system, including methods for randomly sampling sets of variables.

• The data module has been entirely overhauled to provide an API for interacting with jsPsych data. This makes it easier to aggregate and analyze data during the experiment, allowing the experiment to be responsive to the data that is generated.

• User interactions are now automatically recorded by jsPsych, allowing experimenters to know when subjects clicked away from an experiment or exited full screen mode.

• Subjects can now be excluded if their browser does not meet certain technical requirements. Currently this features supports checking for minimum screen size and audio support.

• Many new plugins, including plugins for the implicit association test, a plugin that can calibrate the size of the subject's display, and a plugin for the serial reaction time task. Many plugins have also been renamed to improve clarity.

• A progress bar will now display while experiment resources are preloaded.

• Automatic vertical and horizontal centering of jsPsych content by default.

• New event handlers for when trials start and when trials have finished loading.

Technical changes

This update also features a large number of technical changes to the jsPsych library. These changes are designed to improve the compatibility of jsPsych with other web frameworks and support our ongoing development efforts towards a graphical experiment builder for jsPsych.

• The jQuery dependency has been removed. All jsPsych code uses standard JavaScript with no dependencies. This change means that plugins now need to make changes to a standard HTMLElement to adjust the display, rather than a jQuery collection.

• Plugins now require an .info property, which specifies the parameters of the plugin and what their default values and types are. We use this information to automate some of the tasks that plugins used to have to complete, such as evaluating function parameters and replacing default values. We mostly use the parameter type information as part of the graphical experiment builder engine, but we do check if the type is a function within jsPsych to handle cases where parameters should not be evaluated before the trial runs.

• A testing suite has been written using Jest to facilitate community development on the project as it grows in scope. The suite has partial coverage right now, and remains an active area of work.

Other changes

Many other smaller changes can be discovered on our updated documentation site at www.jspsych.org

v5.0.3

Fixes example files that did not work with v5.x

v5.0.2

• Fixes a critical bug with pre-loading audio files. If more than one audio file was required, the pre-loading would fail. This is now fixed.
• The parameter randomize_order for timelines was being incorrectly applied to timelines that were nested under the randomized timeline. This is now fixed; randomize_order will only apply to the timeline that it is set on.