6.3 Release Notes

[jodeleeuw]

New Features

• Added the concept of extensions to the jsPsych architecture. Extensions are code modules that are designed to extend the functionality of any plugin. Eye tracking is an example of a feature best supported via an extension. The extension is responsible for gathering gaze data and adding the data to the trial. The advantage of using an extension is that the feature can then be added on top of any existing plugin. See the new extensions documentation for more information (Extend plugin architecture to better handle data-generating overlays #1123, Plugin Extensions and Eye Tracking via WebGazer #1516).
• Eye tracking is now available via an extension that utilizes the 3rd party WebGazer library. See the new eye tracking overview in the documentation, plus example experiments in the /examples folder (Plugin Extensions and Eye Tracking via WebGazer #1516).
• Three new plugins to support eye tracking. jspsych-webgazer-init-camera will initialize the camera for eye tracking, jspsych-webgazer-calibrate performs calibration, and jspsych-webgazer-validate performs validation and report data about the accuracy and sampling rate of the eye tracking (Plugin Extensions and Eye Tracking via WebGazer #1516).
• Added the virtual-chinrest plugin, an implementation of the procedure described by Li, Joo, Yeatman, and Reinecke (2020) for measuring the distance between the participant and the monitor. This plugin also merges in features from the resize plugin to allow for scaling of the display to known dimensions, e.g., ensuring that 200px = 2cm. Thanks @GEJ1 and @pjkohler! (virtual-chinrest plugin, with resizing ability #1442)
• New css_classes parameter available in all plugins. This allows you to add one or more custom CSS classes to the display element on that trial, which makes it easier to change style/formatting across trials. For more information, see the new Controlling Visual Appearance documentation page and the "css_classes_parameter.html" example file (Custom CSS class per trial #832, Feature: css_classes trial parameter #1378)
• New save_trial_parameters parameter available in all plugins. This allows you to override the plugin's default trial data, by saving additional parameter values that are not normally saved, or not saving parameter values that normally are saved. For more information, see the parameters available in all plugins page and the "save_trial_parameters.html" example file (allow any parameter from the trial object to be added to the data easily #823, Merge feature-params-in-data - fixes #823 #1555)
• jsPsych.version() returns the version of jspsych.js as a string (Provide version number #1472).
• jsPsych.allTimelineVariables() returns all the timeline variables and their values at that moment in the experiment (Retrieving all timeline variables for a given trial #1237, Add allTimelineVariables() feature #1493)
• It's now possible to use dynamic parameters (functions as parameters) in nested trial parameters. For instance, in the questions parameter in survey-* plugins, you can use a function for any of the individual parameters in each question object, like the prompt. See the updated documentation on dynamic parameters. (Allow nested parameter values to be functions #988, Merge feature-nested-function-parameters branch - fixes #988 #1497)
• The new preload plugin now handles all media preloading. This makes preloading more customizable, and it makes it easy to preload files at any point during an experiment. This plugin contains new options for things error messanges and handling file loading success/failure. For more details, see the preload plugin documentation. Thanks @javidalpe! (Improve loading error messages #1234, Move preloading behavior to a plugin #1351).
• The freesort plugin now works on mobile devices, and includes a new column_spread_factor parameter to control the spread of image columns to the right and left sides of the sort area. Thanks @kurokida! (for using the free-sort plugin with a touch device. #1228, Merge freesort touchscreen updates from #1228 #1546)
• Added and updated documentation on the jsPsych website (Docs reorganization, move 'dynamic params' to its own page #1374), including new pages about:
  • dynamic parameters
  • using and creating plugins
  • links to tutorial videos
  • integrating with Prolific
  • controlling the visual appearance of your experiment
• on_timeline_start and on_timeline_finish callbacks allow you to run arbitrary code at the start/end of at timeline node (including timeline variables, conditional/loop nodes, etc.). See the Timeline and Event-related callback functions pages for info and examples. (keep events for timelines and trials separate #585, Merge the feature timeline events branch #1512)

Changes

• Keys must be given as strings in trial parameters (e.g. choices: ['a']) and are saved as strings in the data (e.g. response: 'a'). Numeric keycodes are no longer accepted and numeric keycodes are no longer used in the data output. This change was made because numeric keycodes are deprecated and future browsers could drop support, so key responses are now recorded using the event's .key property. Key strings are also easier to work with and produce more readable data.
• Because .key based responses distinguish between upper and lower case input, a new flag was added to jsPsych.init called case_sensitive_responses. This setting is false by default, but you can set this flag to true if you want case sensitivity for your key choice parameters and participants' keyboard responses. This setting does not affect responses that are typed into text boxes. For a full summary of the changes related to this shift, see Merge feature-key-code-update branch #1465 and the jsPsych.init documentation. (Use .key property for string-based key codes. #396, Merge feature-key-code-update branch #1465).
• We now recommend using jsPsych.pluginAPI.compareKeys to compare keys in all plugin and experiment code, rather than using something like if (response == 'j').... Using this compareKeys function will ensure that your key comparisons work appropriately based on the experiment's case_sensitive_responses setting. See the compareKeys documentation for more information.
• Media preloading is no longer done through jsPsych.init, so the preloading-related parameters in jsPsych.init are no longer supported (show_preload_progress_bar, preload_audio, preload_images, preload_video, max_load_time, max_preload_attempts). Please use the new preload plugin instead.
• jsPsych plugins can now store complex trial data as JavaScript objects and arrays, instead of JSON-encoded strings. This fixes problems with parsing jsPsych JSON data that were caused by nested JSON strings. This also means you no longer need to use JSON.parse during an experiment to access data that is stored in objects/arrays (e.g. responses to survey-* questions), and plugins should not use JSON.stringify when saving trial data. (Problem outputting nested stringified data to JSON. #670, Merge branch feature-objects-arrays-in-data - fixes #670 #1523)
• In an effort to standardize the response variable names across plugins, many data property names have been changed to response. Examples of data properties that have changed include key_press (*-keyboard-response trials), button_pressed (*-button-response trials), and responses (survey-* trials). In some cases, the data structure has changed so that response information can be stored in a single response property (e.g. maxdiff and serial-reaction-time-mouse plugins). These changes were made in order to reduce the number of different columns and empty cells that are generated when jsPsych data is stored in tabular format, such as CSV. For more information, see the documentation for specific plugins, and this list of all data property name/structure changes across plugins. (standardize the response variable in the data #638, Standardize response data #1529)
• You can now use the jsPsych.timelineVariable function without second the true argument. This function will determine whether or not it should return the timeline variable value immediately, based on the context in which it's called. Thanks @vijaymarupudi! (Allow timelineVariable() to work in functions with no modification #883, Merge feature-timeline-variable-simplify - fixes #883 #1376)
• jsPsych.pluginAPI.getAudioBuffer() will now attempt to load audio files that haven't been preloaded. This means that preloading audio files is no longer strictly necessary, though of course it is still highly recommended. In order to make this feature possible, getAudioBuffer() now returns a Promise and plugins that use this method have been updated. (audio-* plugins don't play audio that hasn't been preloaded #1527, fix-audio-preload #1543)

Bug Fixes

• Fixed problem that was causing the response_allowed_while_playing parameter not to work in the audio-button-response and video-button-response plugins when custom button_html was used. (response_allowed_while_playing plugin doesn't seem to be working #1380, fixes allow_response_while_playing parameter when custom button_html is used #1380 #1384)
• Fixed bug in image-* plugins that was causing images not to be displayed when images were not preloaded and when render_on_canvas was true (the default). (render_on_canvas: true doesn't work when images aren't preloaded? #1305, add img onload fn to draw image when loaded - fixes #1305 #1375)
• Improved documentation and fixed various documentation errors. Thanks @pablobernabeu and @alexanderrobertson! (Fixed typo in media-preloading.md #1413, Update style.md #1401, Update jspsych-survey-text.md #672)
• The fullscreen plugin now checks to see if fullscreen mode is active before trying to exit fullscreen. Thanks @klanderson! (Check fullscreen is active before exiting fullscreen #1354)