@jspsych/plugin-survey-multi-choice 1.1.3 → 2.0.0

package/src/index.ts

@@ -1,72 +1,110 @@
 import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
 
+import { version } from "../package.json";
+
 const info = <const>{
   name: "survey-multi-choice",
+  version: version,
   parameters: {
-    /** Array containing one or more objects with parameters for the question(s) that should be shown on the page. */
+    /**
+     * An array of objects, each object represents a question that appears on the screen. Each object contains a prompt,
+     * options, required, and horizontal parameter that will be applied to the question. See examples below for further
+     * clarification.`prompt`: Type string, default value is *undefined*. The string is prompt/question that will be
+     * associated with a group of options (radio buttons). All questions will get presented on the same page (trial).
+     * `options`: Type array, defualt value is *undefined*. An array of strings. The array contains a set of options to
+     * display for an individual question.`required`: Type boolean, default value is null. The boolean value indicates
+     * if a question is required('true') or not ('false'), using the HTML5 `required` attribute. If this parameter is
+     * undefined, the question will be optional. `horizontal`:Type boolean, default value is false. If true, then the
+     * question is centered and the options are displayed horizontally. `name`: Name of the question. Used for storing
+     * data. If left undefined then default names (`Q0`, `Q1`, `...`) will be used for the questions.
+     */
     questions: {
       type: ParameterType.COMPLEX,
       array: true,
-      pretty_name: "Questions",
       nested: {
         /** Question prompt. */
         prompt: {
           type: ParameterType.HTML_STRING,
-          pretty_name: "Prompt",
           default: undefined,
         },
         /** Array of multiple choice options for this question. */
         options: {
           type: ParameterType.STRING,
-          pretty_name: "Options",
           array: true,
           default: undefined,
         },
         /** Whether or not a response to this question must be given in order to continue. */
         required: {
           type: ParameterType.BOOL,
-          pretty_name: "Required",
           default: false,
         },
         /** If true, then the question will be centered and options will be displayed horizontally. */
         horizontal: {
           type: ParameterType.BOOL,
-          pretty_name: "Horizontal",
           default: false,
         },
         /** Name of the question in the trial data. If no name is given, the questions are named Q0, Q1, etc. */
         name: {
           type: ParameterType.STRING,
-          pretty_name: "Question Name",
           default: "",
         },
       },
     },
-    /** If true, the order of the questions in the 'questions' array will be randomized. */
+    /**
+     * If true, the display order of `questions` is randomly determined at the start of the trial. In the data object,
+     * `Q0` will still refer to the first question in the array, regardless of where it was presented visually.
+     */
     randomize_question_order: {
       type: ParameterType.BOOL,
-      pretty_name: "Randomize Question Order",
       default: false,
     },
-    /** HTML-formatted string to display at top of the page above all of the questions. */
+    /** HTML formatted string to display at the top of the page above all the questions. */
     preamble: {
       type: ParameterType.HTML_STRING,
-      pretty_name: "Preamble",
       default: null,
     },
-    /** Label of the button to submit responses. */
+    /** Label of the button. */
     button_label: {
       type: ParameterType.STRING,
-      pretty_name: "Button label",
       default: "Continue",
     },
-    /** Setting this to true will enable browser auto-complete or auto-fill for the form. */
+    /**
+     * This determines whether or not all of the input elements on the page should allow autocomplete. Setting
+     * this to true will enable autocomplete or auto-fill for the form.
+     */
     autocomplete: {
       type: ParameterType.BOOL,
-      pretty_name: "Allow autocomplete",
       default: false,
     },
   },
+  data: {
+    /** An object containing the response for each question. The object will have a separate key (variable) for each question, with the first question in the trial being recorded in `Q0`, the second in `Q1`, and so on. The responses are recorded as integers, representing the position selected on the likert scale for that question. If the `name` parameter is defined for the question, then the response object will use the value of `name` as the key for each question. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    response: {
+      type: ParameterType.COMPLEX,
+      nested: {
+        identifier: {
+          type: ParameterType.STRING,
+        },
+        response: {
+          type:
+            ParameterType.STRING |
+            ParameterType.INT |
+            ParameterType.FLOAT |
+            ParameterType.BOOL |
+            ParameterType.OBJECT,
+        },
+      },
+    },
+    /** The response time in milliseconds for the participant to make a response. The time is measured from when the questions first appear on the screen until the participant's response(s) are submitted. */
+    rt: {
+      type: ParameterType.INT,
+    },
+    /** 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]`. This will be encoded as a JSON string when data is saved using the `.json()` or `.csv()` functions. */
+    question_order: {
+      type: ParameterType.INT,
+      array: true,
+    },
+  },
 };
 
 type Info = typeof info;
@@ -74,10 +112,10 @@ type Info = typeof info;
 /**
  * **survey-multi-choice**
  *
- * jsPsych plugin for presenting multiple choice survey questions
+ * The survey-multi-choice plugin displays a set of questions with multiple choice response fields. The participant selects a single answer.
  *
  * @author Shane Martin
- * @see {@link https://www.jspsych.org/plugins/jspsych-survey-multi-choice/ survey-multi-choice plugin documentation on jspsych.org}
+ * @see {@link https://www.jspsych.org/latest/plugins/survey-multi-choice/ survey-multi-choice plugin documentation on jspsych.org}
  */
 class SurveyMultiChoicePlugin implements JsPsychPlugin<Info> {
   static info = info;
@@ -226,7 +264,6 @@ class SurveyMultiChoicePlugin implements JsPsychPlugin<Info> {
         response: question_data,
         question_order: question_order,
       };
-      display_element.innerHTML = "";
 
       // next trial
       this.jsPsych.finishTrial(trial_data);