This is the readme for version 2 of the timed-categories field plug-in. To learn about version 1, click here. For the main readme, click here.
In version 2 of the timed-categories field plug-in, respondents have unlimited time to select a choice, but they are timed on how long it took to select the choice. They also cannot advance until they select the correct choice. Learn about the features here.
The field will have a value of the selected choice. The actual field value is not important, since it should always be the value of the "correct" choice.
Metadata is where the important field data is stored.
You can retrieve the metadata using the plug-in-metadata() function. Metadata is stored in a space-separated list, and you can retrieve each part using the selected-at() function. For example, if the field "metadata" is a calculate field that uses the plug-in-metadata() function to retrieve the metadata, and you wanted the second item in the metadata list, you can use this expression:
selected-at(${metadata}, 1)
There are four items in the metadata list:
0 Initial timestamp (internal): The Unix timestamp of when the respondent initially reached the field. This is used for internal purposes, and it is unlikely you will need it.
1 Correct: If the respondent initially selected the correct choice, this will have a value of 1. If the respondent initially selected the wrong choice, this will have a value of 0
2 Time to answer: How long it took in milliseconds to select a choice the first time, regardless of whether they selected the correct choice the first time.
3 Time to correct: How long it took in milliseconds to select the correct choice. If they selected the correct choice the first time, this will be the exact same as item 2.
To use this field plug-in as-is, just download the timed-categories.fieldplugin.zip file from this repo, and attach it to your form.
To use with the sample form:
- Download the sample form from this repo.
- Download the crops_list.csv (downloads as ZIP file you can attach directly to your form).
- Download the timed-categories.fieldplugin.zip file from this repo.
- Upload the form to your server with the CSV and ZIP files attached.
You can also check out this sample form, which demonstrates the parameters and other features. In addition to the main data file and the field plug-in, attach this file to this sample form.
All choices in the choice list will be choices the respondent can select. Each of those choices will have a column in the field display, and they will be selectable by the respondent using either a keyboard key or by clicking.
The value of each choice will be the keyboard key to press to select that choice. For example, if a choice has a value of e, then if the respondent presses the "E" key on their keyboard, then that choice will be selected, and the field will auto-advance.
All choice values that are letters should be lowercase (they will be displayed in uppercase in the field, but the choice values themselves need to be lowercase). To set up a choice so it is selected when the spacebar is pressed, give that choice a value of space (this is demonstrated in field "instructions" the sample form).
Parameters are used to customize the field plug-in. Two of them are required, but the rest are optional.
These two parameters are required, and they should be used whenever you use version 2 of the field plug-in.
| Name | Description | Default |
|---|---|---|
version |
To use version 2 of this field plug-in, give the version parameter a value of 2. Otherwise, version 1 will be used instead. |
1 |
correct |
The "correct" choice. The respondent cannot move forward until they select this choice. If this is not defined, then the first choice in the choice list will be considered the "correct" choice. If the respondent selects the correct answer, then the selected choice will turn green, and show a checkmark. If they select the wrong answer, the selected choice will turn red, and show an X. That way, the respondent gets instant feedback. The value of this parameter should be the same as the correct choice value, but in quotes. For example, if the correct choice has a value of |
These are other parameters you can use in your form, but they are a lot less common. They are all optional.
| Name | Description | Default |
|---|---|---|
unit |
Unit to be used for the display time. For example, if 5 seconds have passed, and You can use |
's' |
showtimer |
If this has a value of 0, then the timer will be hidden (though it will still track the time in the background). |
1 |
hidekeys |
Normally, the keyboard key used to select a choice will appear below the choice label. If this parameter has a value of 1, then it will not show those keyboard keys. This can be helpful if the form will only be completed on a mobile device, where the correct choice will only be selected by clicking/tapping. |
0 |
allowkeys |
Whether or not keyboard keys can be used to select a choice. If this parameter has a value of 0, then keyboard keys cannot be used to select a choice, only clicking/tapping. It will also hide the keyboard keys usually shown below the choice labels, since they are not needed. |
1 |
allowclick |
Whether or not clicking/tapping a choice on the choice column can be used to select a choice. If this parameter has a value of 0, then clicking/tapping the choice cannot be used to select a choice, only keyboard keys. |
1 |
frame_adjust (advanced) |
The field plug-in has been formatted so the tappable area takes up as much of the screen as possible, but without making it so big that the page becomes scrollable. If you would like to make the clickable area bigger or smaller, use this parameter to define how many pixels it should be adjusted by. For example, to make the clickable area 50 pixels taller, give this parameter a value of 50. To make the clickable area 10 pixels shorter, give this parameter a value of -10. |
0 |
You can also check out this sample form, which demonstrates the parameters and other features. In addition to the main data file and the field plug-in, attach this file to this sample form.
- If the form is going to be completed as a web form, for the Collect settings, you may want to set Disable swipe navigation to ON. That way, if the respondent's finger slips while completing the form on mobile, they will not accidentally swipe backwards to the last field. To adjust web form settings, on the Collect tab of your server console, go to the form, and click Settings.
- You can use the "randomized" appearance to randomize the order of the choice columns.
- If you are going to use a
unitother than seconds, it is a good idea to tell the respondent before they start the test, so they are prepared, and they can focus on the test. - If you do not like the size of the timer circle, the colors, or something else, you can change the field plug-in files. Check out our guide on customizations.
| Feature / Property | Support |
|---|---|
| Supported field type(s) | select_one |
| Default values | No |
| Custom constraint message | No |
| Custom required message | No |
| Read only | Yes |
| media:image | Yes |
| media:audio | Yes |
| media:video | Yes |
label appearance |
No |
list-nolabel appearance |
No |
quick appearance |
No |
minimal appearance |
No |
compact appearance |
No |
compact-# appearance |
No |
quickcompact appearance |
No |
quickcompact-# appearance |
No |
likert appearance |
No |
likert-min appearance |
No |
likert-mid appearance |
No |
-
Sample form 1
You can find the main form definition here. You will also need the crops_list.csv file. -
Sample form 2
You can find the other form definition here. You will need to attach this file. -
Developer documentation
More instructions for developing and using field plug-ins can be found here: https://github.com/surveycto/Field-plug-in-resources