Setting a minimum viewing time in instructions

[martinakavanova]

Hi,

I am using the instructions plugin but I would like to let people continue (i.e. display the next button) only after a few seconds have passed, to force them to read the instructions properly and not click through. I have seen this in a previous question where @jodeleeuw suggested modifying the instructions plugin, but I am new to javaScript and don't really know how this would be done. It seems like a pretty common requirement for experiments so maybe there is a simple way?

The only way I can think of is creating separate two trials for each page in the instructions with one set to NO_KEYS and a [x] trial_duration and another with choices of keys. But that seems inefficient with many pages of instructions.

Thank you for any help!

[becky-gilbert]

Hi @martinakavanova, great question. Maybe this is an option that should be added to the instructions plugin. Feel free to open a new issue with this suggestion, and then we can track it 😃

You're right that Josh's suggestion about waiting for the audio to finish before allowing someone to continue is relevant, except in your case we're just waiting for a specific amount of time to pass. We can do this by disabling the next button and keyboard listeners when the trial first starts, and then using the jsPsych.pluginAPI.setTimeout function to enable the next button and keyboard listeners after the minimum viewing time.

To disable the next button when the trial first starts, add the word disabled in the button tag, which is on lines 126-128. You can add in anywhere in the button opening tag, for instance, after the class:

nav_html += "<button id='jspsych-instructions-next' class='jspsych-btn' disabled "+ // <-- add disabled property here
  "style='margin-left: 5px;'>"+trial.button_label_next+
  " &gt;</button></div>";

If you also want the previous button to be disabled, you would do the same thing on line 121:

nav_html += "<button id='jspsych-instructions-back' class='jspsych-btn' style='margin-right: 5px;' disabled >&lt; "+ 
  trial.button_label_previous+"</button>";

To ignore the key presses that move the pages backwards and forwards, we need to remove the keyboard listener that is set up when the trial first starts, which is on lines 226-233. Instead of setting this up right away when the trial starts, we want to wait until the minimum viewing time has passed.

Now we need to add the jsPsych.pluginAPI.setTimeout function, which will wait for a specific amount of time, and then (1) enable the next/previous buttons, and (2) start the keyboard listeners. The second argument is the amount of time to wait, in ms, so the example below will wait for 5 seconds before allowing the participant to continue. I would put this somewhere towards the bottom of the plugin.trial function, for instance, around line 226.

jsPsych.pluginAPI.setTimeout(function() {
  // if allow_keys is true, then start keyboard listeners
  if (trial.allow_keys) {
    var keyboard_listener = jsPsych.pluginAPI.getKeyboardResponse({
      callback_function: after_response,
      valid_responses: [trial.key_forward, trial.key_backward],
      rt_method: 'performance',
      persist: false
    });
  }
  // if show_clickable_nav is true, then enable the buttons
  if (trial.show_clickable_nav) {
    // enable next button
    display_element.querySelector('#jspsych-instructions-next').disabled = false;
    // enable previous button (only if this isn't the first page and allow_backward is true)
    if (current_page != 0 && trial.allow_backward) {
      display_element.querySelector('#jspsych-instructions-back').disabled = false;
    }
  }
}, 5000);

I haven't tested this so it may not work! Feel free to follow up here if you have any problems or further questions.

[becky-gilbert]

Oops, just realized that my other answer won't work because we need to disable the buttons and ignore the key presses until enough time has passed at the start of every page, not just when the whole trial starts! So I got this to work using a different approach.

First, I left the keyboard listener as it was before, so that it's set up when the trial starts, but in the after_response function, I checked whether the min_viewing_time parameter was set, and if so, whether enough time has passed. If min_viewing_time parameter is set and enough time has passed, then the next page is shown. If enough time hasn't passed yet, then the key press is registered but it doesn't cause the next page to be shown.

if (jsPsych.pluginAPI.compareKeys(info.key, trial.key_forward)) {
  var curr_time = performance.now() - last_page_update_time;
  // only show the next page if there's no min_viewing_time, or if there is and enough time has passed
  if (trial.min_viewing_time == null || curr_time > trial.min_viewing_time) { 
    next();
  }
}

Then, in the show_current_page function, I disabled the next button if the min_viewing_time parameter is set:

nav_html += "<button id='jspsych-instructions-next' class='jspsych-btn'"+
  "style='margin-left: 5px;' ";
if (trial.min_viewing_time !== null) {
  nav_html += " disabled ";  // <-- add disabled property to next button if there's a min_viewing_time
}
nav_html += ">"+trial.button_label_next+
  " &gt;</button></div>";

Also in the show_current_page function, after the click event listener is added to the next button, if the min_viewing_time parameter is set then I set up a timer that will enable the next button after the min_viewing_time duration. We also need to include the jsPsych.pluginAPI.clearAllTimeouts(); function here to clear any timers that were set up on the last page (because the participant is allowed to go backwards through the instructions pages before the min_viewing_time has been reached).

if (trial.min_viewing_time !== null) {
  // clear any old timers 
  jsPsych.pluginAPI.clearAllTimeouts();
  // set up a timer to enable the next button after enough time has passed
  next_btn_timer = jsPsych.pluginAPI.setTimeout(function() {
   display_element.querySelector('#jspsych-instructions-next').disabled = false;
  }, trial.min_viewing_time)
}

Finally, it's good practice to clear all timeouts when the trial ends, so I added this to the end_trial function:

if (trial.min_viewing_time !== null) {
  jsPsych.pluginAPI.clearAllTimeouts();
}

I've attached my modified plugin version as a txt file - you'll just want to change the file extenstion back to .js. I hope this helps. Feel free to follow up if you have questions.
jspsych-instructions-min-viewing-time.txt

[martinakavanova]

Thank you so much for this! That's really great :)

[Ir1d]

A quick approach is to modify the on_load function in each trial.

https://www.jspsych.org/7.0/developers/extension-development/#on_load

                on_load(params){
                    var button = document.getElementById("jspsych-survey-text-next");
                    button.style.visibility = "hidden";
                    setTimeout(function() {
                    button.style.visibility = "visible";
                    }, 4000);
                },

[jxwb125646]

But this approach is useful for the first page of the instructions plugin; for other pages, this approach doesn't work. Why?