diff --git a/.changeset/polite-toes-roll.md b/.changeset/polite-toes-roll.md new file mode 100644 index 0000000000..12c320b2ca --- /dev/null +++ b/.changeset/polite-toes-roll.md @@ -0,0 +1,5 @@ +--- +"@jspsych/plugin-instructions": minor +--- + +Run on_page_change upon entering the first page diff --git a/docs/plugins/instructions.md b/docs/plugins/instructions.md index 4fad509949..ae9058c675 100644 --- a/docs/plugins/instructions.md +++ b/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 diff --git a/packages/plugin-instructions/src/index.spec.ts b/packages/plugin-instructions/src/index.spec.ts index 6ed199784b..bacb18eb7e 100644 --- a/packages/plugin-instructions/src/index.spec.ts +++ b/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]); }); }); diff --git a/packages/plugin-instructions/src/index.ts b/packages/plugin-instructions/src/index.ts index 248ea53789..c8ddd318b2 100644 --- a/packages/plugin-instructions/src/index.ts +++ b/packages/plugin-instructions/src/index.ts @@ -65,7 +65,7 @@ const info = { 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 { 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 { 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 { }; show_current_page(); + trial.on_page_change(0, null); if (trial.allow_keys) { var keyboard_listener = this.jsPsych.pluginAPI.getKeyboardResponse({