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 |
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.
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.
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.
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.
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
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.