diff --git a/packages/plugin-survey-html-form/src/index.ts b/packages/plugin-survey-html-form/src/index.ts index 5487fba8..e5c0d9d9 100644 --- a/packages/plugin-survey-html-form/src/index.ts +++ b/packages/plugin-survey-html-form/src/index.ts @@ -1,56 +1,76 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych"; +import { version } from "../package.json"; + const info = { name: "survey-html-form", + version: version, parameters: { /** HTML formatted string containing all the input elements to display. Every element has to have its own distinctive name attribute. The
tag must not be included and is generated by the plugin. */ html: { type: ParameterType.HTML_STRING, - pretty_name: "HTML", default: null, }, /** 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, }, /** The text that appears on the button to finish the trial. */ button_label: { type: ParameterType.STRING, - pretty_name: "Button label", default: "Continue", }, /** The HTML element ID of a form field to autofocus on. */ autofocus: { type: ParameterType.STRING, - pretty_name: "Element ID to focus", default: "", }, /** Retrieve the data as an array e.g. [{name: "INPUT_NAME", value: "INPUT_VALUE"}, ...] instead of an object e.g. {INPUT_NAME: INPUT_VALUE, ...}. */ dataAsArray: { type: ParameterType.BOOL, - pretty_name: "Data As Array", default: false, }, /** Setting this to true will enable browser auto-complete or auto-fill for the form. */ autocomplete: { type: ParameterType.BOOL, - pretty_name: "Allow autocomplete", default: false, }, }, + data: { + /** An object containing the response for each input. The object will have a separate key (variable) for the response to each input, with each variable being named after its corresponding input element. Each response is a string containing whatever the participant answered for this particular input. 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. */ + rt: { + type: ParameterType.INT, + }, + }, }; type Info = typeof info; /** - * **survey-html-form** - * - * jsPsych plugin for displaying free HTML forms and collecting responses from all input elements * + * The survey-html-form plugin displays a set of `` from a HTML string. The type of input can be freely + * chosen, for a list of possible input types see the [MDN page on inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). + * The participant provides answers to the input fields. * @author Jan Simson - * @see {@link https://www.jspsych.org/plugins/jspsych-survey-html-form/ survey-html-form plugin documentation on jspsych.org} + * @see {@link https://www.jspsych.org/latest/plugins/survey-html-form/ survey-html-form plugin documentation on jspsych.org} */ class SurveyHtmlFormPlugin implements JsPsychPlugin { static info = info; diff --git a/packages/plugin-survey-likert/src/index.ts b/packages/plugin-survey-likert/src/index.ts index 9d92ac38..cb18b355 100644 --- a/packages/plugin-survey-likert/src/index.ts +++ b/packages/plugin-survey-likert/src/index.ts @@ -1,37 +1,35 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych"; +import { version } from "../package.json"; + const info = { name: "survey-likert", + version: version, parameters: { /** Array containing one or more objects with parameters for the question(s) that should be shown on the page. */ questions: { type: ParameterType.COMPLEX, array: true, - pretty_name: "Questions", nested: { /** Question prompt. */ prompt: { type: ParameterType.HTML_STRING, - pretty_name: "Prompt", default: undefined, }, /** Array of likert labels to display for this question. */ labels: { type: ParameterType.STRING, array: true, - pretty_name: "Labels", 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, }, /** 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: "", }, }, @@ -39,45 +37,67 @@ const info = { /** If true, the order of the questions in the 'questions' array will be randomized. */ 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. */ preamble: { type: ParameterType.HTML_STRING, - pretty_name: "Preamble", default: null, }, /** Width of the likert scales in pixels. */ scale_width: { type: ParameterType.INT, - pretty_name: "Scale width", default: null, }, /** Label of the button to submit responses. */ 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. */ 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; /** - * **survey-likert** - * - * jsPsych plugin for gathering responses to questions on a likert scale + * The survey-likert plugin displays a set of questions with Likert scale responses. The participant responds + * by selecting a radio button. * * @author Josh de Leeuw - * @see {@link https://www.jspsych.org/plugins/jspsych-survey-likert/ survey-likert plugin documentation on jspsych.org} + * @see {@link https://www.jspsych.org/latest/plugins/survey-likert/ survey-likert plugin documentation on jspsych.org} */ class SurveyLikertPlugin implements JsPsychPlugin { static info = info; diff --git a/packages/plugin-survey-multi-choice/src/index.ts b/packages/plugin-survey-multi-choice/src/index.ts index 1b19bb4a..502b38a1 100644 --- a/packages/plugin-survey-multi-choice/src/index.ts +++ b/packages/plugin-survey-multi-choice/src/index.ts @@ -1,72 +1,110 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych"; +import { version } from "../package.json"; + const info = { 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 { static info = info; diff --git a/packages/plugin-survey-multi-select/src/index.ts b/packages/plugin-survey-multi-select/src/index.ts index 403c6a79..00423fec 100644 --- a/packages/plugin-survey-multi-select/src/index.ts +++ b/packages/plugin-survey-multi-select/src/index.ts @@ -1,88 +1,124 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych"; +import { version } from "../package.json"; + const info = { name: "survey-multi-select", + 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 select options for this question. */ options: { type: ParameterType.STRING, - pretty_name: "Options", array: true, default: undefined, }, /** If true, then the question will be centered and options will be displayed horizontally. */ horizontal: { type: ParameterType.BOOL, - pretty_name: "Horizontal", default: false, }, /** Whether or not a response to this question must be given in order to continue. */ required: { type: ParameterType.BOOL, - pretty_name: "Required", 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. */ button_label: { type: ParameterType.STRING, - pretty_name: "Button label", default: "Continue", }, - /** Message that will be displayed if one or more required questions is not answered. */ + /** 'You must choose at least one response for this question' | Message to display if required response is not given. */ required_message: { type: ParameterType.STRING, - pretty_name: "Required message", default: "You must choose at least one response for this question", }, - /** 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; /** - * **survey-multi-select** + * The survey-multi-select plugin displays a set of questions with multiple select response fields. The participant can + * select multiple answers. * - * jsPsych plugin for presenting multiple choice survey questions with the ability to respond with more than one option - * - * @see {@link https://www.jspsych.org/plugins/jspsych-survey-multi-select/ survey-multi-select plugin documentation on jspsych.org} + * @see {@link https://www.jspsych.org/latest/plugins/survey-multi-select/ survey-multi-select plugin documentation on jspsych.org} */ class SurveyMultiSelectPlugin implements JsPsychPlugin { static info = info; diff --git a/packages/plugin-survey-text/src/index.ts b/packages/plugin-survey-text/src/index.ts index e5445a51..151336ce 100644 --- a/packages/plugin-survey-text/src/index.ts +++ b/packages/plugin-survey-text/src/index.ts @@ -1,88 +1,123 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych"; +import { version } from "../package.json"; + const info = { name: "survey-text", + version: version, parameters: { + /** + * 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", default: undefined, nested: { /** Question prompt. */ prompt: { type: ParameterType.HTML_STRING, - pretty_name: "Prompt", default: undefined, }, /** Placeholder text in the response text box. */ placeholder: { type: ParameterType.STRING, - pretty_name: "Placeholder", default: "", }, /** The number of rows for the response text box. */ rows: { type: ParameterType.INT, - pretty_name: "Rows", default: 1, }, /** The number of columns for the response text box. */ columns: { type: ParameterType.INT, - pretty_name: "Columns", default: 40, }, /** Whether or not a response to this question must be given in order to continue. */ required: { type: ParameterType.BOOL, - pretty_name: "Required", 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. */ 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. */ 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; /** - * **survey-text** * - * jsPsych plugin for free text response survey questions + * The survey-text plugin displays a set of questions with free response text fields. The participant types in answers. * * @author Josh de Leeuw - * @see {@link https://www.jspsych.org/plugins/jspsych-survey-text/ survey-text plugin documentation on jspsych.org} + * @see {@link https://www.jspsych.org/latest/plugins/survey-text/ survey-text plugin documentation on jspsych.org} */ class SurveyTextPlugin implements JsPsychPlugin { static info = info; diff --git a/packages/plugin-survey/src/index.ts b/packages/plugin-survey/src/index.ts index 7d6716a5..a068d7ff 100644 --- a/packages/plugin-survey/src/index.ts +++ b/packages/plugin-survey/src/index.ts @@ -20,7 +20,6 @@ const info = { survey_json: { type: ParameterType.OBJECT, default: {}, - pretty_name: "Survey JSON object", }, /** * @@ -33,7 +32,6 @@ const info = { survey_function: { type: ParameterType.FUNCTION, default: null, - pretty_name: "Survey function", }, /** * A function that can be used to validate responses. This function is called whenever the SurveyJS `onValidateQuestion` @@ -43,7 +41,6 @@ const info = { validation_function: { type: ParameterType.FUNCTION, default: null, - pretty_name: "Validation function", }, }, data: {