Specify a survey page with free text responding

The trial_survey_text function is used to display a survey page that allows free text responding.

trial_survey_text(
  questions,
  preamble = "",
  randomize_question_order = FALSE,
  button_label = "Continue",
  post_trial_gap = 0,
  on_finish = NULL,
  on_load = NULL,
  data = NULL
)

Arguments

questions	A question or list of questions
preamble	Text to appear above the questions
randomize_question_order	Should order be randomised?
button_label	Text for the continue 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

Value

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.

Details

The trial_survey_text function creates a trial that displays a set of questions with free text responses.

Survey construction

There are four arguments that are relevant to the survey itself:

The main argument is questions, which can and can either consist of a single question object generated by question_text or a list of such objects. See the documentation for the question function for details of what this entails.
The preamble argument is used to specify introductory text that appears about the survey page. It accepts HTML markup and so can be used quite flexibly.
The randomize_question_order argument is a logical value that indicates whether or not the survey items should appear in a random order.
The button_label specifies text to appear on the button displayed at the bottom of the page, and which the participant must click before moving on to the next trial.

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 responses value is a string in JSON format containing the response for each question. The encoded object will have a separate variable for the response to each question, with the first question in the trial being recorded in Q0, the second in Q1, and so on. Each response is a string containing whatever the subject typed into the associated text box. If the name parameter is defined for the question, then the response will use the value of name as the key for the response in the responses object.
The rt value is the response time in milliseconds for the subject to make a response. The time is measured from when the questions first appear on the screen until the subject's response.
The question_order value is a string in JSON format containing an array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0], and the final question was trial.questions[1].

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