Merge pull request #496 from brown-ccv/add-countdown-trial

feat: add sample countdown trial that counts down before the start of…

src/experiment/honeycomb.js

@@ -3,6 +3,7 @@ import { buildHoneycombProcedure } from "./procedures/honeycombProcedure";
 import { buildStartProcedure } from "./procedures/startProcedure";
 
 import { buildDebriefTrial, instructionsTrial, preloadTrial } from "./trials/honeycombTrials";
+import { buildCountdownTrial } from "./trials/countdown";
 
 /**
  * ! This file should not be edited! Instead, create a new file with the name of your task
@@ -47,8 +48,12 @@ export function buildHoneycombTimeline(jsPsych) {
   // Builds the trials that make up the end procedure
   const endProcedure = buildEndProcedure(jsPsych);
 
+  // Builds a countdown trial that counts down for 3000ms
+  const countdownTrial = buildCountdownTrial(3000);
+
   const timeline = [
     startProcedure,
+    countdownTrial,
     preloadTrial,
     instructionsTrial,
     honeycombProcedure,

src/experiment/trials/countdown.js

@@ -0,0 +1,33 @@
+import htmlKeyboardResponse from "@jspsych/plugin-html-keyboard-response";
+import { h1 } from "../../lib/markup/tags";
+import { getTimeString } from "../../lib/utils";
+
+/**
+ * a sample countdown trial that counts down ms before another trial begins
+ *
+ * @param {number} ms - millisecond to countdown
+ * @returns a JS object as a trial
+ */
+export function buildCountdownTrial(waitTime) {
+  return {
+    type: htmlKeyboardResponse,
+    stimulus:
+      h1("The next part of the experiment will start in") +
+      h1(getTimeString(waitTime), {
+        id: "clock",
+      }),
+    choices: "NO_KEYS",
+    trial_duration: waitTime + 20,
+    on_load: function () {
+      const startTime = performance.now();
+      const interval = setInterval(function () {
+        const timeLeft = waitTime - (performance.now() - startTime);
+        document.querySelector("#clock").innerHTML = getTimeString(timeLeft);
+        if (timeLeft <= 0) {
+          document.querySelector("#clock").innerHTML = "0:00";
+          clearInterval(interval);
+        }
+      }, 250);
+    },
+  };
+}

src/lib/utils.js

@@ -81,3 +81,33 @@ export function getProlificId() {
 export function interleave(arr, val, addBefore = true) {
   return [].concat(...arr.map((n) => (addBefore ? [val, n] : [n, val])));
 }
+
+/**
+ * Given a millisecond value, returns how many full minutes there are (rounding down)
+ *
+ * @param {number} ms - millisecond
+ * @returns total minutes within the provided ms
+ */
+export function getMinute(ms) {
+  return Math.floor(ms / 1000 / 60);
+}
+
+/**
+ * Given a millisecond value, calculates how many full minutes are within those milliseconds and return the left-over time as the seconds
+ *
+ * @param {number} ms - millisecond
+ * @returns how many seconds are left after excluding the full minutes within the provided ms
+ */
+export function getSeconds(ms) {
+  return Math.floor((ms - getMinute(ms) * 1000 * 60) / 1000);
+}
+
+/**
+ * Gets the time (millisecond) in string format to display on screen
+ *
+ * @param {number} ms - millisecond
+ * @returns return time string format, example: 00:03 (min:seconds)
+ */
+export function getTimeString(ms) {
+  return `${getMinute(ms)}:${getSeconds(ms).toString().padStart(2, "0")}`;
+}