trial_instructions: Specify pages of instructions to display
In djnavarro/jaysire: Build jsPsych Experiments in R

Description Usage Arguments Details Value

The trial_instructions function is used to display one or more pages of instructions that a participant can browse.

trial_instructions(
  pages,
  key_forward = keycode("right arrow"),
  key_backward = keycode("left arrow"),
  allow_backward = TRUE,
  allow_keys = TRUE,
  show_clickable_nav = FALSE,
  button_label_previous = "Previous",
  button_label_next = "Next",
  post_trial_gap = 0,
  on_finish = NULL,
  on_load = NULL,
  data = NULL
)

`pages`	Character vector. Each element should be an HTML-formatted string specifying a page
`key_forward`	This is the key that the subject can press in order to advance to the next page, specified as their numeric key code or as characters
`key_backward`	This is the key that the subject can press in order to return to the previous page.
`allow_backward`	If TRUE, participants can navigate backwards
`allow_keys`	If TRUE, participants can use keyboard keys to navigate
`show_clickable_nav`	If TRUE, buttons will be shown to allow navigation
`button_label_previous`	Text on the "previous" button
`button_label_next`	Text on the "next" button
`post_trial_gap`	The gap in milliseconds between the current trial and the next trial. If NULL, there will be no gap.
`on_finish`	A javascript callback function to execute when the trial finishes
`on_load`	A javascript callback function to execute when the trial begins, before any loading has occurred
`data`	An object containing additional data to store for the trial

The trial_instructions() function is used to generate trials that show instruction to the participant. It allows participants to navigate through multiple pages of instructions at their own pace, recording how long thet spend on each page. Navigation can be done using the mouse or keyboard. Participants can be allowed to navigate forwards and backwards through pages, if desired.

Specifying instructions

The pages argument is a required argument, and should be a character vector. Each element of the vector specifies the text to be displayed on a single instruction page, and can include HTML markup. Depending on parameter values, instruction pages can be navigated by clicking on screen buttons or else by using key presses.
To navigate using buttons, the show_clickable_nav argument must be set to TRUE. If allow_backward is also set to TRUE this will create two buttons on screen, one allowing the participant to move forward to the next page, and another allowing them to move backward to the previous page. If allow_backward = FALSE, only the forward button is shown. The text labels for these buttons can be customised using the button_label_previous and button_label_next arguments.
To navigate using key presses, the allow_keys argument must be set to TRUE. By default, the keyboard navigation uses the right arrow to move forward, and the the left arrow key to move back, but these can be customised using the key_forward and key_backward arguments. The values for these arguments should either be a numeric keycode or the corresponding character code. For an overview of these codes, see the keycode() function documentation.

Other behaviour

Like all functions in the trial_ family it contains four additional arguments:

The post_trial_gap argument is a numeric value specifying the length of the pause between the current trial ending and the next one beginning. This parameter overrides any default values defined using the build_experiment function, and a blank screen is displayed during this gap period.
The on_load and on_finish arguments can be used to specify javascript functions that will execute before the trial begins or after it ends. The javascript code can be written manually and inserted *as* javascript by using the insert_javascript function. However, the fn_ family of functions supplies a variety of functions that may be useful in many cases.
The data argument can be used to insert custom data values into the jsPsych data storage for this trial

Data

When this function is called from R it returns the trial object that will later be inserted into the experiment when build_experiment is called. However, when the trial runs as part of the experiment it returns values that are recorded in the jsPsych data store and eventually form part of the data set for the experiment.

The data recorded by this trial is as follows:

The view_history value is a JSON string containing the order of pages the subject viewed (including when the subject returned to previous pages) and the time spent viewing each page.
The rt value is the response time in milliseconds for the subject to view all of the pages.

In addition, it records default variables that are recorded by all trials:

trial_type is a string that records the name of the plugin used to run the trial.
trial_index is a number that records the index of the current trial across the whole experiment.
time_elapsed counts the number of milliseconds since the start of the experiment when the trial ended.
internal_node_id is a string identifier for the current "node" in the timeline.

Functions with a trial_ prefix always return a "trial" object. A trial object is simply a list containing the input arguments, with NULL elements removed. Logical values in the input (TRUE and FALSE) are transformed to character vectors "true" and "false" and are specified to be objects of class "json", ensuring that they will be written to file as the javascript logicals, true and false.