jsPsych/docs/plugins/jspsych-form.md

jspsych-form

This plugin creates a form from a JSON schema.

Parameters

Parameters with a default value of undefined must be specified. Other parameters can be left unspecified if the default value is acceptable.

Parameter	Type	Default Value	Description
schema	object	{}	A JSON schema that holds the values of settings for creating a form.

JSON schema

Parameter	Type	Default Value	Description
form	Class Form	{}	Values of settings for the form layout.
"any question string"	Classes start from here	undefined	Take the key string as the question title, and the value as question settings.
onSubmit	Class Button	{label: "Submit"}	Values of settings for the button in the form.

Function

createForm

INPUTS: display_element {string}, schema {object}
OUTPUTS: an array, [Object Form, [Object Tag], Object Button]
SIDE EFFECT: Render the form.

schema.type	Effect
"short answer/text"	Instantiate a InputText object.
"long answer/textarea"	Instantiate a Textarea object.
dropdown	Instantiate a Dropdown object.
"checkbox/switch/radio"	Instantiate a ToggleGroup object according to its toggle type.
range	Instantiate its according object (see Class)
date	Instantiate its according object (see Class)
datetime	Instantiate its according object (see Class)
datetime-local	Instantiate its according object (see Class)
email	Instantiate its according object (see Class)
file	Instantiate its according object (see Class)
month	Instantiate its according object (see Class)
password	Instantiate its according object (see Class)
search	Instantiate its according object (see Class)
telephone	Instantiate its according object (see Class)
time	Instantiate its according object (see Class)
url	Instantiate its according object (see Class)
week	Instantiate its according object (see Class)

Class

If the value is in bold, then it is final.
If the value is undefined, then it must be specified.
For MDL color attributes, see MDL colors.
For MDL icons, see MDL icons.
For html color attributes, see html colors.
Mainly used:
Form,
Dropdown
InputText,
Textarea
ToggleGroup

Form

Parameter	Type	Default Value	Description
display_element	string	undefined	Indicate where the form is displayed.
id	numeric	Automactically Assigned	The id of the form.
type	string	"form"	The type of the form.
item	object	{}	Values of settings for the form layout.
item.layout_color	string	white-300	The background color of the layout.
item.boxShadow	numeric	4	The darkness of shadow for the box. 0 - 17
item.form_title	string	"Untitled Form"	The title of the form.
item.form_title_size	string	40px	The font size of the title.
item.form_title_color	string	black-800	The font color of the title.
item.form_description	string	""	The description of the form.
item.form_description_size	string	14px	The font size of the description of the form.
item.form_description_color	string	grey-600	The font color of the description of the form.
item.ribbon_color	string	white-300	The background color of the ribbon.
item.ribbon_height	string	40vh	The height of the ribbon.
item.ribbon_bg	string	""	The background picture of the ribbon.
item.ribbon_bg_size	string	background-size: contain cover;	The background picture's size of the ribbon.
item.content_bg_color	string	white-300	The background color of the content.
item.content_text_color	string	black-800	The font color of the text in the content.

Button

Inheritence: Tag

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"button"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	False	Whether Displaying Question Title.
item.onclick	function	undefined	Add customized submit actions. If it has output, the output will occupy the key "#Customized Output#" in trial_data. (Pre-defined actions are: 1. check if all required fields are filled 2. Compare inputs with expected answers if provided)
item.label	string	"Submit"	The label for the button.
item.buttonStyle	string	"raise"	see MDL attribute
item.color	boolean	True	see MDL attribute
item.primary	boolean	False	see MDL attribute
item.accent	boolean	False	see MDL attribute
item.ripple	boolean	True	see MDL attribute
item.icon	string	""	see MDL attribute

Dropdown

Inheritence: Tag
Drop down a list of option.

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"select"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.options	array	[]	An array of options.
item.choose_prompt	string	"CHOOSE"	Prompt for choosing.
item.dropRight	boolean	True	From which direction the list drops down.

InputDate

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"date"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

InputDatetime

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"datetime"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

InputDatetimeLocal

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"datetime-local"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

InputEmail

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"email"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

InputMonth

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"month"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

InputNumber

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"number"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.label	string	"Please enter a number..."	General inner html content.

InputEmail

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"email"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

InputPassword

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"password"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	False	Whether Displaying Question Title.
item.floating	boolean	True	see MDL attribute
item.label	string	"Please your password..."	General inner html content.

InputSearch

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"email"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	False	Whether Displaying Question Title.
item.icon	string	"search"	see MDL attribute
item.expandable	boolean	True	see MDL attribute
item.floating	boolean	True	see MDL attribute

InputTel

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"tel"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.label	string	"Please your telephone number..."	General inner html content.

InputText

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"text"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.label	string	"Please enter some texts..."	General inner html content.
item.pattern	string	".*"	see html attribute

InputTime

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"time"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

InputUrl

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"url"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.label	string	"Please enter the url..."	General inner html content.

InputWeek

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"week"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.

Range

Inheritence: Tag
Generate a slider.

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"range"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.value_prompt	string	"value: "	Prompt for the value.
item.width	string	300px	see html attribute
item.max	numeric	100	see html attribute
item.min	numeric	0	see html attribute
item.step	numeric	1	see html attribute

Textarea

Inheritence: InputTextField

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"textarea"	The type of the tag.
item.id	string	Automactically Assigned	The id of the tag.
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.placeholder	string	"Text lines"	see html attribute
item.cols	numeric	30	see html attribute
item.rows	numeric	10	see html attribute
item.wrap	string	""	see html attribute

ToggleGroup

Inheritence: Tag
Dependency: Checkbox, Switch, Radio

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.id	string	Automactically Assigned	The id of the tag.
item.type	string	"checkbox"	The type of the toggle_type.
item.needQuestion	boolean	True	Whether Displaying Question Title.
item.labels	array	[]	An array of labels for the options.
item.images	array	[]	An array of images for the options.
item.values	array	[]	An array of values for the options. If None, will take values from item.labels first and then item.images, i.e item.values.length = item.labels.length + item.images.length.
item.correctAnswers	array	[]	An array of expected answers.

UploadFile

Inheritence: Tag

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.id	string	Automactically Assigned	The id of the tag.
item.type	string	"file"	The type of the toggle_type.
item.needQuestion	boolean	False	Whether Displaying Question Title.
item.fileType	string	"Upload a file from here"	Prompt for uploading a file.
item.icon	string	"cloud_upload"	see MDL icons

Base Class

Tag

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element
item	object	{}	An object of values for setting
item.type	string	Automactically Assigned	The type of the tag
item.id	string	Automactically Assigned	The id of the tag
item.needQuestion	boolean	True	Whether Displaying Question Title
item.label	string		General Inner Html Content
item.correct	custom	undefined	The Expected Answer
item.question	string	"Untitled Question"	Question Title
item.question_description	string	""	Question Description
item.question_color	string	black-800	Color Of Question
item.question_description_size	string	14px	Font Size Of Question Description
item.question_description_color	string	grey-600	Color Of Question Description
item.newline	boolean	False	Whether Inserting New Line When Rendering
item.value	string	""	see html attribute
item.name	string	""	see html attribute
item.disabled	boolean	False	see html attribute
item.maxlength	boolean	False	see html attribute
item.readonly	boolean	False	see html attribute
item.required	boolean	False	see html attribute
item.autofocus	boolean	False	see html attribute
item.size	string	""	see html attribute

InputTextField

Inheritence: Tag

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element
item	object	{}	An object of values for setting
item.expandable	boolean	False	see MDL attribute
item.floating	boolean	False	see MDL attribute
item.icon	string	""	see MDL attribute
item.errorInfo	string	"Your input is not as required!"	see MDL attribute
item.pattern	string	".*"	see html attribute
item.accessKey	string	""	see html attribute
item.defaultValue	string	""	see html attribute
item.alt	string	""	see html attribute
item.tabIndex	string	""	see html attribute

Toggle

Inheritence: Tag

Parameter	Type	Default Value	Description
item.needQuestion	boolean	False	Whether Displaying Question Title.
item.toggle_type	string	"checkbox"	The toggle type.
item.newline	boolean	False	Whether Inserting New Line When Rendering.
item.ripple	boolean	True	see MDL attribute
item.value	string	item.label	see html attribute
item.checked	boolean	False	see html attribute

Checkbox

Inheritence: Toggle

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"checkbox"	The type of the tag.
item.toggle_type	string	"checkbox"	The type of the toggle.
item.id	string	Automactically Assigned	The id of the tag.
item.label	string	Automactically Assigned	The label of the option.

Switch

Inheritence: Toggle

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"checkbox"	The type of the tag.
item.toggle_type	string	"switch"	The type of the toggle.
item.id	string	Automactically Assigned	The id of the tag.
item.label	string	Automactically Assigned	The label of the option.

Radio

Inheritence: Toggle

Parameter	Type	Default Value	Description
parent_id	numeric	Form.id	The id of its parent element.
item	object	{}	An object of values for setting.
item.type	string	"radio"	The type of the tag.
item.toggle_type	string	"radio"	The type of the toggle.
item.id	string	Automactically Assigned	The id of the tag.
item.label	string	Automactically Assigned	The label of the option.

Examples

	function clickToSubmit() {
		document.getElementById("custom_id_1").value += "Customize actions when submit buttons is pressed.";
		alert("This is a test. Check Question #7 to see the effect.");
		return {"Customized output": "Customize actions when submit buttons is pressed."};
	}
	
	var schema = {
		form: {form_title: 'Test #1', ribbon_bg: "img/ribbon.jpg", layout_color: "grey-300", content_bg_color: "grey-100"},
		"Question #1": {type: "short answer", correct: "Answer #1", required: true},
		"Question #2": {type: "password"},
		"Question #3": {type: "checkbox", labels: ["option1", "option2"], correctAnswers: ["option1", "option2"]},
		"Question #4": {type: "radio", labels: ["option1", "option2"], correctAnswers: ["option1"]},
		"Question #5": {type: "range"},
		"Question #6": {type: "dropdown"},
		"Question #7": {type: "long answer", question_description: "Some random contents", id: "custom_id_1"},
		"Question #8<p>Some random contents</p>": {type: "long answer", question_description: ""},
		"Question #9": {type: "file"},
		onSubmit: {label: "Submit", onclick: clickToSubmit}
	}

	var form_trial = {
		type: 'form',
		schema: schema
	}

	jsPsych.init({
		timeline: [form_trial],
		on_finish: function(){ jsPsych.data.displayData(); }
	});