Change behavior of on_page_change

.changeset/polite-toes-roll.md

@@ -0,0 +1,5 @@
+---
+"@jspsych/plugin-instructions": minor
+---
+
+Run on_page_change upon entering the first page

docs/plugins/instructions.md

@@ -20,7 +20,7 @@ In addition to the [parameters available in all plugins](../overview/plugins.md#
 | button_label_next     | string   | 'Next'        | The text that appears on the button to go forwards. |
 | show_page_number      | boolean  | false         | If true, and clickable navigation is enabled, then Page x/y will be shown between the nav buttons. |
 | page_label            | string   | 'Page'        | The text that appears before x/y pages displayed when show_page_number is true. |
-| on_page_change  | function | ``function (current_page) {}`` | The function that is called every time the page changes. This function receives a single argument `current_page`, which is the index of the current page **after page change**, and starts at `0`. The function is also called when going forward from the last page, i.e., finishing the trial. |
+| on_page_change  | function | ``function (current_page) {}`` | The function that is called upon trial start and every time the page changes afterwards. This function receives two arguments: `current_page`, which is the index of the current page **after page change**, and `from_page`, which is the index of the previous page the subject has been viewing. Both parameters start at `0`. The function is also called when going forward from the last page, i.e., finishing the trial. |
 
 ## Data Generated
 

packages/plugin-instructions/src/index.spec.ts

@@ -65,13 +65,17 @@ describe("instructions plugin", () => {
   });
 
   test("forward and backward callback works", async () => {
-    let count = [0, 0, 0, 0];
+    let count = [0, 0, 0];
+    let from = [];
     const { expectFinished } = await startTimeline([
       {
         type: instructions,
         pages: ["page 1", "page 2", "page 3"],
-        on_page_change: function (page_number: number) {
-          count[page_number]++;
+        on_page_change: function (page_number: number | null, from_page: number | null) {
+          if (page_number != null) {
+            count[page_number]++;
+          }
+          from.push(from_page);
         },
       },
     ]);
@@ -88,11 +92,12 @@ describe("instructions plugin", () => {
     // Go to last page; count[2]++
     await pressKey("ArrowRight");
 
-    // Finish trial; count[3]++
+    // Finish trial
     await pressKey("ArrowRight");
     await expectFinished();
 
-    expect(count).toEqual([1, 2, 1, 1]);
+    expect(count).toEqual([2, 2, 1]);
+    expect(from).toEqual([null, 0, 1, 0, 1, 2]);
   });
 });
 

packages/plugin-instructions/src/index.ts

@@ -65,7 +65,7 @@ const info = <const>{
     on_page_change: {
       type: ParameterType.FUNCTION,
       pretty_name: "Page change callback",
-      default: function (current_page: number) {},
+      default: function (current_page: number | null, from_page: number | null) {},
     },
   },
   data: {
@@ -194,7 +194,7 @@ class InstructionsPlugin implements JsPsychPlugin<Info> {
         show_current_page();
       }
 
-      trial.on_page_change(current_page);
+      trial.on_page_change(current_page >= trial.pages.length ? null : current_page, current_page - 1);
     }
 
     function back() {
@@ -204,7 +204,7 @@ class InstructionsPlugin implements JsPsychPlugin<Info> {
 
       show_current_page();
 
-      trial.on_page_change(current_page);
+      trial.on_page_change(current_page, current_page + 1);
     }
 
     function add_current_page_to_view_history() {
@@ -255,6 +255,7 @@ class InstructionsPlugin implements JsPsychPlugin<Info> {
     };
 
     show_current_page();
+    trial.on_page_change(0, null);
 
     if (trial.allow_keys) {
       var keyboard_listener = this.jsPsych.pluginAPI.getKeyboardResponse({