Merge pull request #95 from Shaobin-Jiang/main

Bug fixes / New feature for countdown extension

.changeset/unlucky-parents-cover.md

@@ -0,0 +1,5 @@
+---
+"@jspsych-contrib/extension-countdown": minor
+---
+
+Bug fixes and new features for getting time left

packages/extension-countdown/README.md

@@ -0,0 +1,99 @@
+# jsPsych Countdown Extension
+
+This extension adds a countdown during a trial.
+
+## Parameters
+
+### Initialization Parameters
+
+None
+
+### Trial Parameters
+
+Trial parameters can be set when adding the extension to a trial object.
+
+```javascript
+let trial = {
+  type: jsPsych...,
+  extensions: [
+    {type: jsPsychExtensionWebgazer, params: {...}}
+  ]
+}
+```
+
+| Parameter | Type | Default Value | Description |
+| --------- | ---- | ------------- | ----------- |
+| time | number | undefined | Time in milliseconds of the countdown |
+| update_time | number | 50 | How often to update the countdown display; in milliseconds |
+| format | function | (time) => String(Math.floor(time / 1000)) | The displayed content of the countdown. Receives the current time left in milliseconds and returns a string for display. |
+
+## Data Generated
+
+None
+
+## Functions
+
+These functions below are provided to enable a better interaction with the countdown. Note that all of the functions below must be prefixed with `jsPsych.extensions.countdown` (e.g. `jsPsych.extensions.countdown.pause()`).
+
+### `pause()`
+
+Pauses the countdown.
+
+### `resume()`
+
+Resumes the countdown.
+
+### `get_time_left()`
+
+Gets how much time there is still left in milliseconds.
+
+## Example
+
+```javascript
+let jsPsych = initJsPsych({
+  extensions: [{ type: jsPsychExtensionCountdown }],
+});
+
+let trial = {
+  type: jsPsychHtmlKeyboardResponse,
+  stimulus: "Hello world",
+  extensions: [
+    {
+      type: jsPsychExtensionCountdown,
+      params: {
+        time: 5000,
+        update_time: 20,
+        format: (time) => {
+          if (time < 3000) {
+            document.querySelector(".jspsych-extension-countdown").style.color = "red";
+          }
+
+          let time_in_seconds = time / 1000;
+
+          let minutes = Math.floor(time_in_seconds / 60);
+          time_in_seconds -= minutes * 60;
+
+          let seconds = Math.floor(time_in_seconds);
+
+          let format_number = (number) => {
+            let temp_str = `0${number}`;
+            return temp_str.substring(temp_str.length - 2);
+          };
+
+          return `${format_number(minutes)}:${format_number(seconds)}`;
+        },
+      },
+    },
+  ],
+  on_load: function () {
+    setTimeout(() => {
+      jsPsych.extensions.countdown.pause();
+      setTimeout(() => {
+        jsPsych.extensions.countdown.resume();
+      }, 2000);
+    }, 1000);
+  },
+};
+
+jsPsych.run([trial]);
+```

packages/extension-countdown/docs/jspsych-countdown.md

@@ -43,6 +43,10 @@ Pauses the countdown.
 
 Resumes the countdown.
 
+### `get_time_left()`
+
+Gets how much time there is still left in milliseconds.
+
 ## Example
 
 ```javascript

packages/extension-countdown/src/index.ts

@@ -45,6 +45,8 @@ class CountdownExtension implements JsPsychExtension {
     this.time = time;
     this.update_time = update_time;
 
+    this.time_elapsed = 0;
+
     this.countdown_element = document.createElement("div");
     this.countdown_element.innerHTML = this.format(time);
     this.countdown_element.className = "jspsych-extension-countdown";
@@ -82,6 +84,10 @@ class CountdownExtension implements JsPsychExtension {
   resume = (): void => {
     this.is_running = true;
   };
+
+  get_time_left = (): number => {
+    return this.time - this.time_elapsed;
+  };
 }
 
 export default CountdownExtension;