<commit_before>### Table of contents

- [Pages](#pages)
	- [Page Timer](#page-timer)
	- [Page Messages](#page-messages)
- [Questions](#questions)
	- [Hooks](#hooks)
	- [Info](#info)
	- [Text & Textarea](#text-textarea)
	- [textNumber](#textnumber)
	- [dropdown](#dropdown)
	- [selectOne & selectMulti](#selectone-selectmulti)
	- [grid](#grid)
	- [slider](#slider)
- [settings](#settings)
	- [onEnd](#onend)
	- [logger](#logger)
	- [Debugging](#debugging)
- [Data](#data)
	- [Logs](#logs)
	- [Variables](#variables)

### Pages
The basic unit in PIquest is the **page**. A page is usually one screen in your questionnaire. If your questionnaire presents all its questions in one screen, it will probably have only one page. The properties within a page manage how the question(s) is(are) displayed and how the participants interact with it (e.g., select an answer and then click a submit button).

property		| description
--------------- | ---------------------
name 			| (text) The identifier for this page, is used mainly for logging
decline 		| (true, false, 'double'. default:false) Whether to allow participants decline to answer the questions on this page. This option displays a "decline" button that proceeds to the next page without validation and marks this response as "declined". If decline is set to 'double' then two click are required in order to decline answering.
declineText		| (text) The text for the decline button (default value: "Decline to answer")
prev 			| (true or false) Whether to allow users to return to the previous page. The previous button does not appear on the first page (default value: false).
prevText		| (text) The text for the previous button (default value: "Go Back")
noSubmit		| (true of false) remove submit button (useful when using the 'autoSubmit' function of some questions; default value: false).
submitText		| (text) The text of the submit button (default: "Submit").
header  		| (text) Text for the page header.
headerStyle		| (Object) A A [css object](#http://api.jquery.com/css/#css-properties)  to set the style of the header (see examples below).
progressBar 	| (text) Text for the progress bar (You might want to use a template for this, maybe something like: `<%= pagesMeta.number %> out of <%= pagesMeta.outOf%>`.).
numbered 		| (true of false) Whether to  display the number of each question (default value: false).
numberStart		| (Number) The number for the first question in the page (default: 1).
timer 			| (Object) This property controls the page timer, its properties are documented right [here](#page-timer).
questions 		| (Array or Object) an array of [questions](#questions) to be displayed in the page. Note that the questions may be randomized and chosen conditionally using a [mixer](#mixer). This property also accepts a single question object if you want to present only a single question per page.
lognow 			| (true or false) Whether to log the questions on this page. This option is useful when you know that the page will not be accessed any more. It allows you to use the `pulse` option from the [logger](#logger) to send questions as they are being answered instead of sending only at the end of the task. (default: false)
animate 		| (text) What types of animation to use when this page enters and leaves the screen. We currently support three animations: fade, slide, and drop-in. You can use any and all of them by adding them to the string (for example: "slide fade" will activate both of these animations).
v1style			| (true or false or 2) Activate in order to use the version 0.1 style. Currently this only affects the way that the submit/decline buttons are presented. Set this to 2 in order to use the latest version of 0.1

For example, a page can look something like this:

```js
var page = {
	header: 'Personal information:',
	headerStyle: {'background-color':'red',color:'blue'},
	decline: true,
	declineText: 'I prefer to keep this information to myself',
	questions: [
		{type:'text', stem:'What is your name?'},
		{type:'text', stem:'Where do you live?'}
	]
}
```

#### Page Timer
The page timer allows you to constrain the time that users have to answer their questions. In order to control it, you may use the following properties.

property		| description
--------------- | ---------------------
duration 		| (number) How long (in seconds) before the timer ends.
submitOnEnd 	| (true or false) Whether to submit when the timer ends (true by default).
show 			| (true or false) Whether to display a visual countdown (true by default).
direction 		| ("up" or "down") Whether to use a countdown or to count up ("down" by default).
removeOnEnd 	| (true or false) Whether to remove the visual timer when the countdown ends (if you don't auto proceed when the timer ends. ).		
message 		| (String or Object) Display a message at the end the timer duration. You can imput a simple string here, but if you want finer control over the content of the message you can use the [object API](#page-messages).

#### Page Messages
You may want to display a message to the users when they run out of time at the end of a timer. Messages can be simple strings, or if you want finer control over the content of the message you can use the object API, that may be used as follows:

property		| description
--------------- | ---------------------
header 			| The header text for the message (defaults to "Timer Done").
body 			| The body of the message.
button 			| The close button (defaults to "close").

All these strings may use templates, and have access to the following objects: `global`, `current`, `pagesData`, `pagesMeta`.

### Questions

Here are the types of questions PIQuest currently supports:
* [info](#info)
* [text & textarea](#text-textarea)
* [textNumber](#textnumber)
* [dropdown](#dropdown)
* [selectOne & selectMulti](#selectone-selectmulti)
* [grid](#grid)
* [slider](#slider)

All question types share some basic properties:

property		| description
--------------- | ---------------------
type 			| (text; default: 'text') Controls the question type. See the possible types below. 
name 			| (text) The name that this question is marked with when it is logged. Also allows you to refer to the question from within PIquest.
stem 			| (text; default: '') The text for the question itself..
stemCss			| A [css object](#http://api.jquery.com/css/#css-properties) to be applied to the stem.
description 	| (text; default: '') Any additional text you want in order to extend the question description.
maxWidth 		| Force question inputs to have this maximum width. The `maxWidth` must include an explicit measuring unit (for example '800px' or '50%').
help			| (true or false;  (default: false)) Whether to display the question help text.
helpText		| (text) The question help text. (Some questions have default help texts, some don't).
lognow 			| (true or false) Whether to log this questions when the page is submitted. This option is useful when you know that the question will not be accessed any more. It allows you to use the `pulse` option from the [logger](#logger) to send questions as they are being answered instead of sending only at the end of the task. (default: false)
errorMsg		| (Object: {}) This object has a property for each validation type. Setting the appropriate type changes the validation message. For instance setting the `required` property will change the validation message for instances where no response was given.

You may want to debug questions by [activating the `question` DEBUG setting](#debugging). You will then be warned in the console if a question name is reused (note: sometimes a question is supposed to be reused, if this warning pops up just make sure the use case is correct).

#### Hooks

Questions have hooks that allow you to respond to many events in the life time of the question. Each hook is invoked with `global`, `current` and the question `log`. 

property		| description
--------------- | ---------------------
onCreate 		| At the creation of the question.
onChange 		| At each change of the question response (note that this hook may be called many times for each question).
onSubmit 		| When the question is submitted.
onDecline 		| When the question is declined.
onTimeout 		| When the timer finishes.
onDestroy 		| When the question is removed from the screen (either decline or submit).

For example, in case the participant made an error you can mark it on the current object:

```js
var questions = {
	stem: 'Please write "Hello"',
	onSubmit: function(log, current){
		// if the question response is not correct
		if (log.response !== 'Hello'){
			// mark an arbitrary flag so that it may be accessed somewhere else
			current.error = true;
		}
	}
}
```

#### Info
The info question isn't strictly a question. It allows you to use the common question properties in order to display information to the users. For example you can use it as follows:

```js
{
	type: 'info',
	description: '<p>The following questions deal with emotions</p>' +
		'<p>Please answer them as honestly as possible</p>'
}
```

This question will simply display the description without offering any additional user interface (explicit question).

#### Text & Textarea
The `text` and `textarea` questions consist of a simple text input in which the users can type in text. The difference between them is that text questions consist of a single line, whereas textareas are multiline. There are also several properties that are unique to textareas.
Both types of questions support the following properties.

property		| description
--------------- | ---------------------
dflt 			| (test; default value: "") The default value for this question.
inline 			| Show the stem in the same line as the input box (this will make the input box narrower as well).
width 			| (Number or text) The width of the input box (By default numbers are translated to pixels, but you can use text to use other units).
autoSubmit 		| (true or false; default: false) If this property is set to true typing `Enter` while this input is focused will submit the page.
minLength 		| (Number) Validation: force at least this number of characters.
minlength 		| @DEPRECATED see minLength. (Number) Validation: force at least this number of characters.
maxlength		| (Number) Validation: force at most this number of characters.
maxlengthLimit 	| (true or false) Do not allow the user to input more characters than defined by `maxlength` (if maxlength is not defined, any number of characters will be allowed).
required		| (true of false; default: false) Validation: require a non-empty string as a response.
pattern			| (text [supports regex]) Validation: require the response to match the regular expression set in pattern (takes either a string <code>"a&#124;b"</code> or a regular expression <code>/a&#124;b/</code>).
correct 		| (true or false; default: false) Validation: require the response to be correct (set the target value using `correctValue`)
correctValue 	| (*) Set the correct response value for the correct validation.
errorMsg		| (Object: {}) This object has a property for each validation type. Setting the appropriate type changes the validation message. For instance setting the `required` property will change the validation message for instances where no response was given.

The following properties are supported only by `textarea`s:

property		| description
--------------- | ---------------------
rows 			| The number of visible text lines.
columns 		| The visible width of the textarea, in average character widths (this setting overrides the width setting).

For example, this is a text question that requires a valid email address (although there are better *patterns* out there for this purpose):
<commit_msg>docs(questDirectives): minLength is deprecated as opposed to minlength<commit_after>### Table of contents

- [Pages](#pages)
	- [Page Timer](#page-timer)
	- [Page Messages](#page-messages)
- [Questions](#questions)
	- [Hooks](#hooks)
	- [Info](#info)
	- [Text & Textarea](#text-textarea)
	- [textNumber](#textnumber)
	- [dropdown](#dropdown)
	- [selectOne & selectMulti](#selectone-selectmulti)
	- [grid](#grid)
	- [slider](#slider)
- [settings](#settings)
	- [onEnd](#onend)
	- [logger](#logger)
	- [Debugging](#debugging)
- [Data](#data)
	- [Logs](#logs)
	- [Variables](#variables)

### Pages
The basic unit in PIquest is the **page**. A page is usually one screen in your questionnaire. If your questionnaire presents all its questions in one screen, it will probably have only one page. The properties within a page manage how the question(s) is(are) displayed and how the participants interact with it (e.g., select an answer and then click a submit button).

property		| description
--------------- | ---------------------
name 			| (text) The identifier for this page, is used mainly for logging
decline 		| (true, false, 'double'. default:false) Whether to allow participants decline to answer the questions on this page. This option displays a "decline" button that proceeds to the next page without validation and marks this response as "declined". If decline is set to 'double' then two click are required in order to decline answering.
declineText		| (text) The text for the decline button (default value: "Decline to answer")
prev 			| (true or false) Whether to allow users to return to the previous page. The previous button does not appear on the first page (default value: false).
prevText		| (text) The text for the previous button (default value: "Go Back")
noSubmit		| (true of false) remove submit button (useful when using the 'autoSubmit' function of some questions; default value: false).
submitText		| (text) The text of the submit button (default: "Submit").
header  		| (text) Text for the page header.
headerStyle		| (Object) A A [css object](#http://api.jquery.com/css/#css-properties)  to set the style of the header (see examples below).
progressBar 	| (text) Text for the progress bar (You might want to use a template for this, maybe something like: `<%= pagesMeta.number %> out of <%= pagesMeta.outOf%>`.).
numbered 		| (true of false) Whether to  display the number of each question (default value: false).
numberStart		| (Number) The number for the first question in the page (default: 1).
timer 			| (Object) This property controls the page timer, its properties are documented right [here](#page-timer).
questions 		| (Array or Object) an array of [questions](#questions) to be displayed in the page. Note that the questions may be randomized and chosen conditionally using a [mixer](#mixer). This property also accepts a single question object if you want to present only a single question per page.
lognow 			| (true or false) Whether to log the questions on this page. This option is useful when you know that the page will not be accessed any more. It allows you to use the `pulse` option from the [logger](#logger) to send questions as they are being answered instead of sending only at the end of the task. (default: false)
animate 		| (text) What types of animation to use when this page enters and leaves the screen. We currently support three animations: fade, slide, and drop-in. You can use any and all of them by adding them to the string (for example: "slide fade" will activate both of these animations).
v1style			| (true or false or 2) Activate in order to use the version 0.1 style. Currently this only affects the way that the submit/decline buttons are presented. Set this to 2 in order to use the latest version of 0.1

For example, a page can look something like this:

```js
var page = {
	header: 'Personal information:',
	headerStyle: {'background-color':'red',color:'blue'},
	decline: true,
	declineText: 'I prefer to keep this information to myself',
	questions: [
		{type:'text', stem:'What is your name?'},
		{type:'text', stem:'Where do you live?'}
	]
}
```

#### Page Timer
The page timer allows you to constrain the time that users have to answer their questions. In order to control it, you may use the following properties.

property		| description
--------------- | ---------------------
duration 		| (number) How long (in seconds) before the timer ends.
submitOnEnd 	| (true or false) Whether to submit when the timer ends (true by default).
show 			| (true or false) Whether to display a visual countdown (true by default).
direction 		| ("up" or "down") Whether to use a countdown or to count up ("down" by default).
removeOnEnd 	| (true or false) Whether to remove the visual timer when the countdown ends (if you don't auto proceed when the timer ends. ).		
message 		| (String or Object) Display a message at the end the timer duration. You can imput a simple string here, but if you want finer control over the content of the message you can use the [object API](#page-messages).

#### Page Messages
You may want to display a message to the users when they run out of time at the end of a timer. Messages can be simple strings, or if you want finer control over the content of the message you can use the object API, that may be used as follows:

property		| description
--------------- | ---------------------
header 			| The header text for the message (defaults to "Timer Done").
body 			| The body of the message.
button 			| The close button (defaults to "close").

All these strings may use templates, and have access to the following objects: `global`, `current`, `pagesData`, `pagesMeta`.

### Questions

Here are the types of questions PIQuest currently supports:
* [info](#info)
* [text & textarea](#text-textarea)
* [textNumber](#textnumber)
* [dropdown](#dropdown)
* [selectOne & selectMulti](#selectone-selectmulti)
* [grid](#grid)
* [slider](#slider)

All question types share some basic properties:

property		| description
--------------- | ---------------------
type 			| (text; default: 'text') Controls the question type. See the possible types below. 
name 			| (text) The name that this question is marked with when it is logged. Also allows you to refer to the question from within PIquest.
stem 			| (text; default: '') The text for the question itself..
stemCss			| A [css object](#http://api.jquery.com/css/#css-properties) to be applied to the stem.
description 	| (text; default: '') Any additional text you want in order to extend the question description.
maxWidth 		| Force question inputs to have this maximum width. The `maxWidth` must include an explicit measuring unit (for example '800px' or '50%').
help			| (true or false;  (default: false)) Whether to display the question help text.
helpText		| (text) The question help text. (Some questions have default help texts, some don't).
lognow 			| (true or false) Whether to log this questions when the page is submitted. This option is useful when you know that the question will not be accessed any more. It allows you to use the `pulse` option from the [logger](#logger) to send questions as they are being answered instead of sending only at the end of the task. (default: false)
errorMsg		| (Object: {}) This object has a property for each validation type. Setting the appropriate type changes the validation message. For instance setting the `required` property will change the validation message for instances where no response was given.

You may want to debug questions by [activating the `question` DEBUG setting](#debugging). You will then be warned in the console if a question name is reused (note: sometimes a question is supposed to be reused, if this warning pops up just make sure the use case is correct).

#### Hooks

Questions have hooks that allow you to respond to many events in the life time of the question. Each hook is invoked with `global`, `current` and the question `log`. 

property		| description
--------------- | ---------------------
onCreate 		| At the creation of the question.
onChange 		| At each change of the question response (note that this hook may be called many times for each question).
onSubmit 		| When the question is submitted.
onDecline 		| When the question is declined.
onTimeout 		| When the timer finishes.
onDestroy 		| When the question is removed from the screen (either decline or submit).

For example, in case the participant made an error you can mark it on the current object:

```js
var questions = {
	stem: 'Please write "Hello"',
	onSubmit: function(log, current){
		// if the question response is not correct
		if (log.response !== 'Hello'){
			// mark an arbitrary flag so that it may be accessed somewhere else
			current.error = true;
		}
	}
}
```

#### Info
The info question isn't strictly a question. It allows you to use the common question properties in order to display information to the users. For example you can use it as follows:

```js
{
	type: 'info',
	description: '<p>The following questions deal with emotions</p>' +
		'<p>Please answer them as honestly as possible</p>'
}
```

This question will simply display the description without offering any additional user interface (explicit question).

#### Text & Textarea
The `text` and `textarea` questions consist of a simple text input in which the users can type in text. The difference between them is that text questions consist of a single line, whereas textareas are multiline. There are also several properties that are unique to textareas.
Both types of questions support the following properties.

property		| description
--------------- | ---------------------
dflt 			| (test; default value: "") The default value for this question.
inline 			| Show the stem in the same line as the input box (this will make the input box narrower as well).
width 			| (Number or text) The width of the input box (By default numbers are translated to pixels, but you can use text to use other units).
autoSubmit 		| (true or false; default: false) If this property is set to true typing `Enter` while this input is focused will submit the page.
minlength 		| (Number) Validation: force at least this number of characters.
minLength 		| @DEPRECATED see minlength. (Number) Validation: force at least this number of characters.
maxlength		| (Number) Validation: force at most this number of characters.
maxlengthLimit 	| (true or false) Do not allow the user to input more characters than defined by `maxlength` (if maxlength is not defined, any number of characters will be allowed).
required		| (true of false; default: false) Validation: require a non-empty string as a response.
pattern			| (text [supports regex]) Validation: require the response to match the regular expression set in pattern (takes either a string <code>"a&#124;b"</code> or a regular expression <code>/a&#124;b/</code>).
correct 		| (true or false; default: false) Validation: require the response to be correct (set the target value using `correctValue`)
correctValue 	| (*) Set the correct response value for the correct validation.
errorMsg		| (Object: {}) This object has a property for each validation type. Setting the appropriate type changes the validation message. For instance setting the `required` property will change the validation message for instances where no response was given.

The following properties are supported only by `textarea`s:

property		| description
--------------- | ---------------------
rows 			| The number of visible text lines.
columns 		| The visible width of the textarea, in average character widths (this setting overrides the width setting).

For example, this is a text question that requires a valid email address (although there are better *patterns* out there for this purpose):

{'fraction_non_alphanumeric': 0.10036131774707757, 'fraction_numerical': 0.0016153028692879915, 'mean_word_length': 3.83278553820871, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2715399', 'n_tokens_mistral': 6246, 'n_tokens_neox': 5936, 'n_words': 3335}