Allow message_progress_bar to be a function

.changeset/stupid-baboons-wait.md

@@ -0,0 +1,5 @@
+---
+"jspsych": major
+---
+
+Allow message_progress_bar to be a function

docs/reference/jspsych.md

@@ -26,7 +26,7 @@ The settings object can contain several parameters. None of the parameters are r
 | on_close                   | function | Function to execute when the user leaves the page. Can be used, for example, to save data before the page is closed. |
 | exclusions                 | object   | Specifies restrictions on the browser the participant can use to complete the experiment. See list of options below. *This feature is deprecated as of v7.1 and will be removed in v8.0. The [browser-check plugin](../plugins/browser-check.md) is an improved way to handle exclusions.* |
 | show_progress_bar          | boolean  | If `true`, then [a progress bar](../overview/progress-bar.md) is shown at the top of the page. Default is `false`. |
-| message_progress_bar       | string   | Message to display next to the progress bar. The default is 'Completion Progress'. |
+| message_progress_bar       | string or function   | Message to display next to the progress bar or a function that returns that message. The default is 'Completion Progress'. If `message_progress_bar` is a function, it receives one single argument which is the current progress, ranging from 0 to 1; the function gets called on every progress bar update automatically. |
 | auto_update_progress_bar   | boolean  | If true, then the progress bar at the top of the page will automatically update as every top-level timeline or trial is completed. |
 | use_webaudio               | boolean  | If false, then jsPsych will not attempt to use the WebAudio API for audio playback. Instead, HTML5 Audio objects will be used. The WebAudio API offers more precise control over the timing of audio events, and should be used when possible. The default value is `true`. |
 | default_iti                | numeric  | The default inter-trial interval in ms. The default value if none is specified is 0ms. |

packages/jspsych/src/ProgressBar.ts

@@ -2,7 +2,10 @@
  * Maintains a visual progress bar using HTML and CSS
  */
 export class ProgressBar {
-  constructor(private readonly containerElement: HTMLDivElement, private readonly message: string) {
+  constructor(
+    private readonly containerElement: HTMLDivElement,
+    private readonly message: string | ((progress: number) => string)
+  ) {
     this.setupElements();
   }
 
@@ -14,7 +17,13 @@ export class ProgressBar {
   /** Adds the progress bar HTML code into `this.containerElement` */
   private setupElements() {
     this.messageSpan = document.createElement("span");
-    this.messageSpan.innerHTML = this.message;
+
+    if (Object.prototype.toString.call(this.message) === "[object Function]") {
+      this.messageSpan.innerHTML = (this.message as (progress: number) => string)(0);
+    } else {
+      // Progress starts at 0 when experiment commences
+      this.messageSpan.innerHTML = this.message as string;
+    }
 
     this.innerDiv = document.createElement("div");
     this.innerDiv.id = "jspsych-progressbar-inner";
@@ -31,6 +40,10 @@ export class ProgressBar {
   /** Updates the progress bar according to `this.progress` */
   private update() {
     this.innerDiv.style.width = this._progress * 100 + "%";
+
+    if (Object.prototype.toString.call(this.message) === "[object Function]") {
+      this.messageSpan.innerHTML = (this.message as (progress: number) => string)(this._progress);
+    }
   }
 
   /**