Merge pull request #3556 from jspsych/patch-video-default-dimensions

fix `video-*-response` plugins to have properly typed default values

Author: jadeddelta

.changeset/blue-carrots-relate.md

@@ -0,0 +1,7 @@
+---
+"@jspsych/plugin-video-keyboard-response": patch
+"@jspsych/plugin-video-button-response": patch
+"@jspsych/plugin-video-slider-response": patch
+---
+
+`width` and `height` default parameters are set to `null` as opposed to an empty string to properly reflect their types

docs/plugins/video-button-response.md

@@ -15,12 +15,12 @@ Parameter | Type | Default Value | Description
 stimulus | array | *undefined* | An array of file paths to the video. You can specify multiple formats of the same video (e.g., .mp4, .ogg, .webm) to maximize the [cross-browser compatibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats). Usually .mp4 is a safe cross-browser option. The plugin does not reliably support .mov files. The player will use the first source file in the array that is compatible with the browser, so specify the files in order of preference.
 choices | array of strings | *undefined* | Labels for the buttons. Each different string in the array will generate a different button.
 button_html | function | ``(choice: string, choice_index: number)=>`<button class="jspsych-btn">${choice}</button>``; | A function that generates the HTML for each button in the `choices` array. The function gets the string and index of the item in the `choices` array and should return valid HTML. If you want to use different markup for each button, you can do that by using a conditional on either parameter. The default parameter returns a button element with the text label of the choice.
-button_layout | string | 'grid' | Setting to `'grid'` will make the container element have the CSS property `display: grid` and enable the use of `grid_rows` and `grid_columns`. Setting to `'flex'` will make the container element have the CSS property `display: flex`. You can customize how the buttons are laid out by adding inline CSS in the `button_html` parameter.
+button_layout | string | `'grid'` | Setting to `'grid'` will make the container element have the CSS property `display: grid` and enable the use of `grid_rows` and `grid_columns`. Setting to `'flex'` will make the container element have the CSS property `display: flex`. You can customize how the buttons are laid out by adding inline CSS in the `button_html` parameter.
 grid_rows | number | 1 | The number of rows in the button grid. Only applicable when `button_layout` is set to `'grid'`. If null, the number of rows will be determined automatically based on the number of buttons and the number of columns.
 grid_columns | number | null | The number of columns in the button grid. Only applicable when `button_layout` is set to `'grid'`. If null, the number of columns will be determined automatically based on the number of buttons and the number of rows.
 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).
-width | numeric | width of the video file | The width of the video display in pixels.
-height | numeric | heigh of the video file | The height of the video display in pixels.
+width | numeric | width of the video file | The width of the video display in pixels. If `null`, the video will take the original video's dimensions, or properly scaled with the aspect ratio if the height is also specified.
+height | numeric | heigh of the video file | The height of the video display in pixels. If `null`, the video will take the original video's dimensions, or properly scaled with the aspect ratio if the width is also specified.
 autoplay | boolean | true | If true, the video will begin playing as soon as it has loaded.
 controls | boolean | false | If true, controls for the video player will be available to the participant. They will be able to pause the video or move the playback to any point in the video.
 start | numeric | null | If given a value, the video will start at this time point in seconds.

docs/plugins/video-keyboard-response.md

@@ -14,8 +14,8 @@ In addition to the [parameters available in all plugins](../overview/plugins.md#
 | ------------------------------ | ---------------- | ----------------------- | ---------------------------------------- |
 | stimulus                       | array            | *undefined*             | An array of file paths to the video. You can specify multiple formats of the same video (e.g., .mp4, .ogg, .webm) to maximize the [cross-browser compatibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats). Usually .mp4 is a safe cross-browser option. The plugin does not reliably support .mov files. The player will use the first source file in the array that is compatible with the browser, so specify the files in order of preference. |
 | 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). |
-| width                          | numeric          | width of the video file | The width of the video display in pixels. |
-| height                         | numeric          | heigh of the video file | The height of the video display in pixels. |
+| width                          | numeric          | width of the video file | The width of the video display in pixels. If `null`, the video will take the original video's dimensions, or properly scaled with the aspect ratio if the height is also specified. |
+| height                         | numeric          | heigh of the video file | The height of the video display in pixels. If `null`, the video will take the original video's dimensions, or properly scaled with the aspect ratio if the width is also specified. |
 | autoplay                       | boolean          | true                    | If true, the video will begin playing as soon as it has loaded. |
 | controls                       | boolean          | false                   | If true, controls for the video player will be available to the participant. They will be able to pause the video or move the playback to any point in the video. |
 | start                          | numeric          | null                    | If given a value, the video will start at this time point in seconds. |

docs/plugins/video-slider-response.md

@@ -14,16 +14,16 @@ Parameter | Type | Default Value | Description
 ----------|------|---------------|------------
 stimulus | array | *undefined* | An array of file paths to the video. You can specify multiple formats of the same video (e.g., .mp4, .ogg, .webm) to maximize the [cross-browser compatibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats). Usually .mp4 is a safe cross-browser option. The plugin does not reliably support .mov files. The player will use the first source file in the array that is compatible with the browser, so specify the files in order of preference.
 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).
-width | numeric | width of the video file | The width of the video display in pixels.
-height | numeric | heigh of the video file | The height of the video display in pixels.
+width | numeric | width of the video file | The width of the video display in pixels. If `null`, the video will take the original video's dimensions, or properly scaled with the aspect ratio if the height is also specified.
+height | numeric | height of the video file | The height of the video display in pixels. If `null`, the video will take the original video's dimensions, or properly scaled with the aspect ratio if the width is also specified.
 autoplay | boolean | true | If true, the video will begin playing as soon as it has loaded.
 controls | boolean | false | If true, controls for the video player will be available to the participant. They will be able to pause the video or move the playback to any point in the video.
 start | numeric | null | If given a value, the video will start at this time point in seconds.
-stop| numeric | null | If given a value, the video will stop at this time point in seconds.
+stop | numeric | null | If given a value, the video will stop at this time point in seconds.
 rate | numeric | null | The playback rate of the video. 1 is normal, <1 is slower, >1 is faster.
 min | integer | 0 | Sets the minimum value of the slider.
 max | integer | 100 | Sets the maximum value of the slider.
-slider_start | integer | 50 | Sets the starting value of the slider
+slider_start | integer | 50 | Sets the starting value of the slider.
 step | integer | 1 | Sets the step of the slider. This is the smallest amount by which the slider can change.
 labels | array of strings | [] | Labels displayed at equidistant locations on the slider. For example, two labels will be placed at the ends of the slider. Three labels would place two at the ends and one in the middle. Four will place two at the ends, and the other two will be at 33% and 67% of the slider width.
 slider_width | integer | null | Set the width of the slider in pixels. If left null, then the width will be equal to the widest element in the display.

examples/jspsych-video-button-response.html

@@ -33,7 +33,7 @@
     var trial_1 = {
       type: jsPsychVideoButtonResponse,
       stimulus: ['video/sample_video.mp4'],
-      choices: ['Y','N'],
+      choices: ['Y', 'N'],
       margin_vertical: '10px',
       margin_horizontal: '8px',
       prompt: 'Press Y or N',
@@ -51,7 +51,7 @@
     var trial_2 = {
       type: jsPsychVideoButtonResponse,
       stimulus: ['video/sample_video.mp4'],
-      choices: ['😄','😁','🥱','😣','🤯'],
+      choices: ['😄', '😁', '🥱', '😣', '🤯'],
       button_html: function (choice) {
         return '<span style="font-size:40px;">' + choice + '</span>';
       },
@@ -68,7 +68,9 @@
       type: jsPsychVideoButtonResponse,
       stimulus: ['video/sample_video.mp4'],
       choices: ['😄','😁','🥱','😣','🤯'],
-      button_html: '<div style="font-size:40px;">%choice%</div>',
+      button_html: function (choice) {
+        return '<span style="font-size:40px;">' + choice + '</span>';
+      },
       margin_vertical: '10px',
       margin_horizontal: '8px',
       prompt: '<p>Click the emoji that best represents your reaction to the video</p><p>Click a button to end the trial.</p><p>Response buttons are disabled for the first 2 seconds of playing.</p>',

examples/jspsych-video-keyboard-response.html

@@ -33,7 +33,7 @@
     var trial_1 = {
       type: jsPsychVideoKeyboardResponse,
       stimulus: ['video/sample_video.mp4'],
-      choices: ['y','n'],
+      choices: ['y', 'n'],
       prompt: 'Press y or n.',
       width: 600,
       //height: 600,

packages/plugin-video-button-response/src/index.ts

@@ -45,15 +45,19 @@ const info = <const>{
       type: ParameterType.HTML_STRING,
       default: null,
     },
-    /** The width of the video display in pixels. */
+    /** The width of the video display in pixels. If `null`, the video will take the original video's dimensions, 
+     * or properly scaled with the aspect ratio if the height is also specified.
+     */
     width: {
       type: ParameterType.INT,
-      default: "",
+      default: null,
     },
-    /** The height of the video display in pixels. */
+    /** The height of the video display in pixels. If `null`, the video will take the original video's dimensions,
+     * or properly scaled with the aspect ratio if the width is also specified.
+     */
     height: {
       type: ParameterType.INT,
-      default: "",
+      default: null,
     },
     /** If true, the video will begin playing as soon as it has loaded. */
     autoplay: {
@@ -68,12 +72,12 @@ const info = <const>{
       type: ParameterType.BOOL,
       default: false,
     },
-    /** Time to start the clip. If null (default), video will start at the beginning of the file. */
+    /** Time to start the clip. If `null` (default), video will start at the beginning of the file. */
     start: {
       type: ParameterType.FLOAT,
       default: null,
     },
-    /** Time to stop the clip. If null (default), video will stop at the end of the file. */
+    /** Time to stop the clip. If `null` (default), video will stop at the end of the file. */
     stop: {
       type: ParameterType.FLOAT,
       default: null,

packages/plugin-video-keyboard-response/src/index.ts

@@ -25,13 +25,17 @@ const info = <const>{
       pretty_name: "Prompt",
       default: null,
     },
-    /** The width of the video in pixels. */
+    /** The width of the video display in pixels. If `null`, the video will take the original video's dimensions, 
+     * or properly scaled with the aspect ratio if the height is also specified.
+     */
     width: {
       type: ParameterType.INT,
       pretty_name: "Width",
       default: "",
     },
-    /** The height of the video display in pixels. */
+    /** The height of the video display in pixels. If `null`, the video will take the original video's dimensions,
+     * or properly scaled with the aspect ratio if the width is also specified.
+     */
     height: {
       type: ParameterType.INT,
       pretty_name: "Height",
@@ -99,7 +103,7 @@ const info = <const>{
     },
     /** The response time in milliseconds for the participant to make a response. The time is measured from when the
      * stimulus first appears on the screen until the participant's response.
-     * */
+     */
     rt: {
       type: ParameterType.INT,
     },
@@ -137,14 +141,6 @@ class VideoKeyboardResponsePlugin implements JsPsychPlugin<Info> {
   constructor(private jsPsych: JsPsych) {}
 
   trial(display_element: HTMLElement, trial: TrialType<Info>) {
-    // catch mistake where stimuli are not an array
-    if (!Array.isArray(trial.stimulus)) {
-      throw new Error(`
-        The stimulus property for the video-keyboard-response plugin must be an array
-        of files. See https://www.jspsych.org/latest/plugins/video-keyboard-response/#parameters
-      `);
-    }
-
     // setup stimulus
     var video_html = "<div>";
     video_html += '<video id="jspsych-video-keyboard-response-stimulus"';

packages/plugin-video-slider-response/src/index.ts

@@ -23,15 +23,19 @@ const info = <const>{
       type: ParameterType.HTML_STRING,
       default: null,
     },
-    /** The width of the video in pixels. */
+    /** The width of the video display in pixels. If `null`, the video will take the original video's dimensions, 
+     * or properly scaled with the aspect ratio if the height is also specified.
+     */
     width: {
       type: ParameterType.INT,
-      default: "",
+      default: null,
     },
-    /** The height of the video display in pixels. */
+    /** The height of the video display in pixels. If `null`, the video will take the original video's dimensions,
+     * or properly scaled with the aspect ratio if the width is also specified.
+     */
     height: {
       type: ParameterType.INT,
-      default: "",
+      default: null,
     },
     /** If true, the video will begin playing as soon as it has loaded. */
     autoplay: {
@@ -191,13 +195,6 @@ class VideoSliderResponsePlugin implements JsPsychPlugin<Info> {
   constructor(private jsPsych: JsPsych) {}
 
   trial(display_element: HTMLElement, trial: TrialType<Info>) {
-    if (!Array.isArray(trial.stimulus)) {
-      throw new Error(`
-        The stimulus property for the video-slider-response plugin must be an array
-        of files. See https://www.jspsych.org/latest/plugins/video-slider-response/#parameters
-      `);
-    }
-
     // half of the thumb width value from jspsych.css, used to adjust the label positions
     var half_thumb_width = 7.5;