Add parameter "enable_button_after" to all "-button-response" plugins (#3289)

.changeset/slimy-planets-change.md

@@ -0,0 +1,8 @@
+---
+"@jspsych/plugin-audio-button-response": minor
+"@jspsych/plugin-html-button-response": minor
+"@jspsych/plugin-image-button-response": minor
+"@jspsych/plugin-video-button-response": minor
+---
+
+Issue (#3289), Add parameter "enable_button_after" to all "-button-response" plugins

contributors.md

@@ -61,3 +61,4 @@ The following people have contributed to the development of jsPsych by writing c
 * Rob Wilkinson - https://github.com/RobAWilkinson
 * Andy Woods - https://github.com/andytwoods
 * Reto Wyss - https://github.com/retowyss
+* Haotian Tu - https://github.com/thtTNT

docs/plugins/audio-button-response.md

@@ -26,6 +26,7 @@ In addition to the [parameters available in all plugins](../overview/plugins.md#
 | 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 button choices are enabled and a response is accepted. Once the audio has played all the way through, the buttons are enabled and a response is allowed (including while the audio is being re-played via on-screen playback controls). |
+| enable_button_after            | numeric          | 0                                              | How long the button will delay enabling in milliseconds. If `response_allowed_while_playing` is `true`, the timer will start immediately. If it is `false`, the timer will start at the end of the audio. |
 
 ## Data Generated
 

docs/plugins/html-button-response.md

@@ -19,6 +19,7 @@ stimulus_duration | numeric | null | How long to display the stimulus in millise
 margin_vertical | string | '0px' | Vertical margin of the button(s).
 margin_horizontal | string | '8px' | Horizontal margin of the button(s).
 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 view a stimulus for a fixed amount of time, even if they respond before the time is complete.
+enable_button_after | numeric | 0 | How long the button will delay enabling in milliseconds.
 
 ## Data Generated
 

docs/plugins/image-button-response.md

@@ -25,6 +25,7 @@ margin_vertical | string | '0px' | Vertical margin of the button(s).
 margin_horizontal | string | '8px' | Horizontal margin of the button(s).
 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 view a stimulus for a fixed amount of time, even if they respond before the time is complete.
 render_on_canvas | boolean | true | If true, the image will be drawn onto a canvas element. This prevents a blank screen (white flash) between consecutive image trials in some browsers, like Firefox and Edge. If false, the image will be shown via an img element, as in previous versions of jsPsych. If the stimulus is an **animated gif**, you must set this parameter to false, because the canvas rendering method will only present static images.
+enable_button_after | numeric | 0 | How long the button will delay enabling in milliseconds.
 
 ## Data Generated
 

docs/plugins/video-button-response.md

@@ -29,6 +29,7 @@ trial_ends_after_video | bool | false | If true, then the trial will end as soon
 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 view a stimulus for a fixed amount of time, even if they respond before the time is complete.
 response_allowed_while_playing | boolean | true | If true, then responses are allowed while the video is playing. If false, then the video must finish playing before the button choices are enabled and a response is accepted. Once the video has played all the way through, the buttons are enabled and a response is allowed (including while the video is being re-played via on-screen playback controls). 
+enable_button_after | numeric | 0 | How long the button will delay enabling in milliseconds. If `response_allowed_while_playing` is `true`, the timer will start immediately. If it is `false`, the timer will start at the end of the video.
 
 
 ## Data Generated

examples/jspsych-audio-button-response.html

@@ -55,6 +55,24 @@
     response_allowed_while_playing: false
   })
 
+  timeline.push({
+    type: jsPsychAudioButtonResponse,
+    stimulus: 'sound/speech_joke.mp3',
+    choices: ['Not funny', 'Funny'],
+    prompt: '<p>Is the joke funny?</p><p>Click a button to end the trial.</p><p>Response buttons are disabled for the first 2 seconds of playing.</p>',
+    response_allowed_while_playing: true,
+    enable_button_after: 2000
+  })
+
+  timeline.push({
+    type: jsPsychAudioButtonResponse,
+    stimulus: 'sound/speech_joke.mp3',
+    choices: ['Not funny', 'Funny'],
+    prompt: '<p>Is the joke funny?</p><p>When the audio stops, click a button to end the trial.</p><p>Response buttons are enabled 2 seconds after the end of playing.</p>',
+    response_allowed_while_playing: false,
+    enable_button_after: 2000
+  })
+
   jsPsych.run(timeline); 
 
   </script>

examples/jspsych-html-button-response.html

@@ -40,6 +40,14 @@
     prompt: "<p>What color is this word? (trial ends after 2s)</p>"
   });
 
+  timeline.push({
+    type: jsPsychHtmlButtonResponse,
+    stimulus: '<p style="color: red; font-size: 48px; font-weight: bold;">GREEN</p>',
+    choices: ['Green', 'Blue', 'Red'],
+    enable_button_after: 2000,
+    prompt: "<p>What color is this word? (button enable after 2s)</p>"
+  });
+
   jsPsych.run(timeline);
 
   </script>

examples/jspsych-image-button-response.html

@@ -88,6 +88,15 @@
       post_trial_gap: 500
     });
 
+    timeline.push({
+      type: jsPsychImageButtonResponse,
+      stimulus: 'img/happy_face_1.jpg',
+      choices: ['Happy', 'Sad'],
+      enable_button_after: 2000,
+      prompt: "<p>What emotion is this person showing? (button enable after 2s)</p>",
+      post_trial_gap: 500
+    });
+
     jsPsych.run(timeline);
 
   </script>

examples/jspsych-video-button-response.html

@@ -62,7 +62,22 @@
       response_allowed_while_playing: false
     };
 
-    jsPsych.run([preload, pre_trial, trial_1, trial_2]);
+    var trail_3 = {
+      type: jsPsychVideoButtonResponse,
+      stimulus: ['video/sample_video.mp4'],
+      choices: ['😄','😁','🥱','😣','🤯'],
+      button_html: '<div style="font-size:40px;">%choice%</div>',
+      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>',
+      width: 600,
+      autoplay: true,
+      response_ends_trial: true,
+      response_allowed_while_playing: true,
+      enable_button_after: 2000
+    }
+
+    jsPsych.run([preload, pre_trial, trial_1, trial_2, trail_3]);
 
   </script>
 </html>

packages/plugin-audio-button-response/src/index.spec.ts

@@ -32,6 +32,37 @@ describe.skip("audio-button-response", () => {
 
     await finished;
   });
+
+  test("enable buttons during audio playback", async () => {
+    const timeline = [
+      {
+        type: audioButtonResponse,
+        stimulus: "mymp3.mp3",
+        prompt: "foo",
+        choices: ["choice1"],
+        response_allowed_while_playing: true,
+        enable_button_after: 500,
+      },
+    ];
+
+    const jsPsych = initJsPsych({
+      use_webaudio: false,
+    });
+
+    const { getHTML, finished } = await startTimeline(timeline, jsPsych);
+
+    const btns = document.querySelectorAll(".jspsych-html-button-response-button button");
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].getAttribute("disabled")).toBe(true);
+    }
+
+    jest.advanceTimersByTime(500);
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].hasAttribute("disabled")).toBe(false);
+    }
+  });
 });
 
 describe("audio-button-response simulation", () => {

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

@@ -68,6 +68,12 @@ const info = <const>{
       pretty_name: "Response allowed while playing",
       default: true,
     },
+    /** The delay of enabling button */
+    enable_button_after: {
+      type: ParameterType.INT,
+      pretty_name: "Enable button after",
+      default: 0,
+    },
   },
 };
 
@@ -177,6 +183,7 @@ class AudioButtonResponsePlugin implements JsPsychPlugin<Info> {
       display_element.innerHTML = html;
 
       if (trial.response_allowed_while_playing) {
+        disable_buttons();
         enable_buttons();
       } else {
         disable_buttons();
@@ -255,6 +262,10 @@ class AudioButtonResponsePlugin implements JsPsychPlugin<Info> {
       trial_complete();
     };
 
+    const enable_buttons_with_delay = (delay: number) => {
+      this.jsPsych.pluginAPI.setTimeout(enable_buttons_without_delay, delay);
+    };
+
     function button_response(e) {
       var choice = e.currentTarget.getAttribute("data-choice"); // don't use dataset for jsdom compatibility
       after_response(choice);
@@ -271,7 +282,7 @@ class AudioButtonResponsePlugin implements JsPsychPlugin<Info> {
       }
     }
 
-    function enable_buttons() {
+    function enable_buttons_without_delay() {
       var btns = document.querySelectorAll(".jspsych-audio-button-response-button");
       for (var i = 0; i < btns.length; i++) {
         var btn_el = btns[i].querySelector("button");
@@ -282,6 +293,14 @@ class AudioButtonResponsePlugin implements JsPsychPlugin<Info> {
       }
     }
 
+    function enable_buttons() {
+      if (trial.enable_button_after > 0) {
+        enable_buttons_with_delay(trial.enable_button_after);
+      } else {
+        enable_buttons_without_delay();
+      }
+    }
+
     return new Promise((resolve) => {
       trial_complete = resolve;
     });
@@ -305,7 +324,9 @@ class AudioButtonResponsePlugin implements JsPsychPlugin<Info> {
   private create_simulation_data(trial: TrialType<Info>, simulation_options) {
     const default_data = {
       stimulus: trial.stimulus,
-      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
+      rt:
+        this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true) +
+        trial.enable_button_after,
       response: this.jsPsych.randomization.randomInt(0, trial.choices.length - 1),
     };
 

packages/plugin-html-button-response/src/index.spec.ts

@@ -153,15 +153,41 @@ describe("html-button-response", () => {
       " responded"
     );
   });
+
+  test("buttons should be disabled first and then enabled after enable_button_after is set", async () => {
+    const { getHTML } = await startTimeline([
+      {
+        type: htmlButtonResponse,
+        stimulus: "this is html",
+        choices: ["button-choice"],
+        enable_button_after: 500,
+      },
+    ]);
+
+    const btns = document.querySelectorAll(".jspsych-html-button-response-button button");
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].getAttribute("disabled")).toBe("disabled");
+    }
+
+    jest.advanceTimersByTime(500);
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].hasAttribute("disabled")).toBe(false);
+    }
+  });
 });
 
 describe("html-button-response simulation", () => {
   test("data mode works", async () => {
+    const ENABLE_BUTTON_AFTER = 2000;
+
     const timeline = [
       {
         type: htmlButtonResponse,
         stimulus: "foo",
         choices: ["a", "b", "c"],
+        enable_button_after: ENABLE_BUTTON_AFTER,
       },
     ];
 
@@ -171,17 +197,20 @@ describe("html-button-response simulation", () => {
 
     const response = getData().values()[0].response;
 
-    expect(getData().values()[0].rt).toBeGreaterThan(0);
+    expect(getData().values()[0].rt).toBeGreaterThan(ENABLE_BUTTON_AFTER);
     expect(response).toBeGreaterThanOrEqual(0);
     expect(response).toBeLessThanOrEqual(2);
   });
 
   test("visual mode works", async () => {
+    const ENABLE_BUTTON_AFTER = 2000;
+
     const timeline = [
       {
         type: htmlButtonResponse,
         stimulus: "foo",
         choices: ["a", "b", "c"],
+        enable_button_after: ENABLE_BUTTON_AFTER,
       },
     ];
 
@@ -200,7 +229,7 @@ describe("html-button-response simulation", () => {
 
     const response = getData().values()[0].response;
 
-    expect(getData().values()[0].rt).toBeGreaterThan(0);
+    expect(getData().values()[0].rt).toBeGreaterThan(ENABLE_BUTTON_AFTER);
     expect(response).toBeGreaterThanOrEqual(0);
     expect(response).toBeLessThanOrEqual(2);
   });

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

@@ -59,6 +59,12 @@ const info = <const>{
       pretty_name: "Response ends trial",
       default: true,
     },
+    /** The delay of enabling button */
+    enable_button_after: {
+      type: ParameterType.INT,
+      pretty_name: "Enable button after",
+      default: 0,
+    },
   },
 };
 
@@ -191,6 +197,20 @@ class HtmlButtonResponsePlugin implements JsPsychPlugin<Info> {
       }, trial.stimulus_duration);
     }
 
+    // disable all the buttons and set a timeout that enables them after a specified delay if timing is set
+    if (trial.enable_button_after > 0) {
+      var btns = document.querySelectorAll(".jspsych-html-button-response-button button");
+      for (var i = 0; i < btns.length; i++) {
+        btns[i].setAttribute("disabled", "disabled");
+      }
+      this.jsPsych.pluginAPI.setTimeout(() => {
+        var btns = document.querySelectorAll(".jspsych-html-button-response-button button");
+        for (var i = 0; i < btns.length; i++) {
+          btns[i].removeAttribute("disabled");
+        }
+      }, trial.enable_button_after);
+    }
+
     // end trial if time limit is set
     if (trial.trial_duration !== null) {
       this.jsPsych.pluginAPI.setTimeout(end_trial, trial.trial_duration);
@@ -215,7 +235,9 @@ class HtmlButtonResponsePlugin implements JsPsychPlugin<Info> {
   private create_simulation_data(trial: TrialType<Info>, simulation_options) {
     const default_data = {
       stimulus: trial.stimulus,
-      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
+      rt:
+        this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true) +
+        trial.enable_button_after,
       response: this.jsPsych.randomization.randomInt(0, trial.choices.length - 1),
     };
 

packages/plugin-image-button-response/src/index.spec.ts

@@ -153,16 +153,43 @@ describe("image-button-response", () => {
     expect(spy).toHaveBeenCalled();
     spy.mockRestore();
   });
+
+  test("delay enable button", async () => {
+    const { getHTML, expectFinished } = await startTimeline([
+      {
+        type: imageButtonResponse,
+        stimulus: "../media/blue.png",
+        choices: ["button-choice"],
+        enable_button_after: 500,
+        render_on_canvas: false,
+      },
+    ]);
+
+    const btns = document.querySelectorAll(".jspsych-image-button-response-button button");
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].getAttribute("disabled")).toBe("disabled");
+    }
+
+    jest.advanceTimersByTime(500);
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].hasAttribute("disabled")).toBe(false);
+    }
+  });
 });
 
 describe("image-button-response simulation", () => {
   test("data mode works", async () => {
+    const ENABLE_BUTTON_AFTER = 2000;
+
     const timeline = [
       {
         type: imageButtonResponse,
         stimulus: "foo.png",
         choices: ["a", "b", "c"],
         render_on_canvas: false,
+        enable_button_after: ENABLE_BUTTON_AFTER,
       },
     ];
 
@@ -172,18 +199,21 @@ describe("image-button-response simulation", () => {
 
     const response = getData().values()[0].response;
 
-    expect(getData().values()[0].rt).toBeGreaterThan(0);
+    expect(getData().values()[0].rt).toBeGreaterThan(ENABLE_BUTTON_AFTER);
     expect(response).toBeGreaterThanOrEqual(0);
     expect(response).toBeLessThanOrEqual(2);
   });
 
   test("visual mode works", async () => {
+    const ENABLE_BUTTON_AFTER = 2000;
+
     const timeline = [
       {
         type: imageButtonResponse,
         stimulus: "foo.png",
         choices: ["a", "b", "c"],
         render_on_canvas: false,
+        enable_button_after: ENABLE_BUTTON_AFTER,
       },
     ];
 
@@ -200,7 +230,7 @@ describe("image-button-response simulation", () => {
 
     const response = getData().values()[0].response;
 
-    expect(getData().values()[0].rt).toBeGreaterThan(0);
+    expect(getData().values()[0].rt).toBeGreaterThan(ENABLE_BUTTON_AFTER);
     expect(response).toBeGreaterThanOrEqual(0);
     expect(response).toBeLessThanOrEqual(2);
   });

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

@@ -86,6 +86,12 @@ const info = <const>{
       pretty_name: "Render on canvas",
       default: true,
     },
+    /** The delay of enabling button */
+    enable_button_after: {
+      type: ParameterType.INT,
+      pretty_name: "Enable button after",
+      default: 0,
+    },
   },
 };
 
@@ -335,6 +341,28 @@ class ImageButtonResponsePlugin implements JsPsychPlugin<Info> {
       }
     }
 
+    function enable_buttons() {
+      var btns = document.querySelectorAll(".jspsych-image-button-response-button button");
+      for (var i = 0; i < btns.length; i++) {
+        btns[i].removeAttribute("disabled");
+      }
+    }
+
+    function disable_buttons() {
+      var btns = document.querySelectorAll(".jspsych-image-button-response-button button");
+      for (var i = 0; i < btns.length; i++) {
+        btns[i].setAttribute("disabled", "disabled");
+      }
+    }
+
+    // set timer of button delay
+    if (trial.enable_button_after > 0) {
+      disable_buttons();
+      this.jsPsych.pluginAPI.setTimeout(() => {
+        enable_buttons();
+      }, trial.enable_button_after);
+    }
+
     // hide image if timing is set
     if (trial.stimulus_duration !== null) {
       this.jsPsych.pluginAPI.setTimeout(() => {
@@ -374,7 +402,9 @@ class ImageButtonResponsePlugin implements JsPsychPlugin<Info> {
   private create_simulation_data(trial: TrialType<Info>, simulation_options) {
     const default_data = {
       stimulus: trial.stimulus,
-      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
+      rt:
+        this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true) +
+        trial.enable_button_after,
       response: this.jsPsych.randomization.randomInt(0, trial.choices.length - 1),
     };
 

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

@@ -25,15 +25,47 @@ describe("video-button-response", () => {
       await jsPsych.run(timeline);
     }).rejects.toThrowError();
   });
+
+  test("enable buttons during video playing", async () => {
+    const timeline = [
+      {
+        type: videoButtonResponse,
+        stimulus: ["foo.mp4"],
+        prompt: "foo",
+        choices: ["choice1"],
+        response_allowed_while_playing: true,
+        enable_button_after: 500,
+      },
+    ];
+
+    const jsPsych = initJsPsych();
+
+    const { getHTML, finished } = await startTimeline(timeline, jsPsych);
+
+    const btns = document.querySelectorAll(".jspsych-html-button-response-button button");
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].getAttribute("disabled")).toBe(true);
+    }
+
+    jest.advanceTimersByTime(500);
+
+    for (let i = 0; i < btns.length; i++) {
+      expect(btns[i].getAttribute("disabled")).toBe(false);
+    }
+  });
 });
 
 describe("video-button-response simulation", () => {
   test("data mode works", async () => {
+    const ENABLE_BUTTON_AFTER = 2000;
+
     const timeline = [
       {
         type: videoButtonResponse,
         stimulus: ["foo.mp4"],
         choices: ["click"],
+        enable_button_after: ENABLE_BUTTON_AFTER,
       },
     ];
 
@@ -41,7 +73,7 @@ describe("video-button-response simulation", () => {
 
     await expectFinished();
 
-    expect(getData().values()[0].rt).toBeGreaterThan(0);
+    expect(getData().values()[0].rt).toBeGreaterThan(ENABLE_BUTTON_AFTER);
     expect(getData().values()[0].response).toBe(0);
   });
 
@@ -49,12 +81,15 @@ describe("video-button-response simulation", () => {
   test("visual mode works", async () => {
     const jsPsych = initJsPsych();
 
+    const ENABLE_BUTTON_AFTER = 2000;
+
     const timeline = [
       {
         type: videoButtonResponse,
         stimulus: ["foo.mp4"],
         prompt: "foo",
         choices: ["click"],
+        enable_button_after: ENABLE_BUTTON_AFTER,
       },
     ];
 
@@ -73,7 +108,7 @@ describe("video-button-response simulation", () => {
 
     await expectFinished();
 
-    expect(getData().values()[0].rt).toBeGreaterThan(0);
+    expect(getData().values()[0].rt).toBeGreaterThan(ENABLE_BUTTON_AFTER);
     expect(getData().values()[0].response).toBe(0);
   });
 });

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

@@ -108,6 +108,12 @@ const info = <const>{
       pretty_name: "Response allowed while playing",
       default: true,
     },
+    /** The delay of enabling button */
+    enable_button_after: {
+      type: ParameterType.INT,
+      pretty_name: "Enable button after",
+      default: 0,
+    },
   },
 };
 
@@ -269,8 +275,12 @@ class VideoButtonResponsePlugin implements JsPsychPlugin<Info> {
         var currenttime = video_element.currentTime;
         if (currenttime >= trial.stop) {
           if (!trial.response_allowed_while_playing) {
+            if (trial.enable_button_after > 0) {
+              enable_buttons_delayed(trial.enable_button_after);
+            } else {
               enable_buttons();
             }
+          }
           video_element.pause();
           if (trial.trial_ends_after_video && !stopped) {
             // this is to prevent end_trial from being called twice, because the timeupdate event
@@ -282,8 +292,17 @@ class VideoButtonResponsePlugin implements JsPsychPlugin<Info> {
       });
     }
 
+    const enable_buttons_delayed = (delay: number) => {
+      this.jsPsych.pluginAPI.setTimeout(enable_buttons, delay);
+    };
+
     if (trial.response_allowed_while_playing) {
+      disable_buttons();
+      if (trial.enable_button_after !== null) {
+        enable_buttons_delayed(trial.enable_button_after);
+      } else {
         enable_buttons();
+      }
     } else {
       disable_buttons();
     }
@@ -393,7 +412,9 @@ class VideoButtonResponsePlugin implements JsPsychPlugin<Info> {
   private create_simulation_data(trial: TrialType<Info>, simulation_options) {
     const default_data = {
       stimulus: trial.stimulus,
-      rt: this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true),
+      rt:
+        this.jsPsych.randomization.sampleExGaussian(500, 50, 1 / 150, true) +
+        trial.enable_button_after,
       response: this.jsPsych.randomization.randomInt(0, trial.choices.length - 1),
     };