Skip to content

Latest commit

 

History

History
124 lines (83 loc) · 13.1 KB

v1.md

File metadata and controls

124 lines (83 loc) · 13.1 KB

Timed categories: Version 1

This is the readme for version 1 of the timed-categories field plug-in. To learn about version 2, click here. For the main readme, click here.

In version 1 of the timed-categories field plug-in, respondents have a set period of time to select a choice, and if a choice is not selected in time, the field will auto-advance. Learn about the features here.

Data format

The field will have a value of the selected choice, or the value of the "pass" choice (discussed more later) if a choice is not selected in time.

Metadata

Metadata is saved if the field is timed, i.e. if the duration parameter has a value.

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 first item in the metadata list, you can use this expression:

selected-at(${metadata}, 0)

There are two or three items in the metadata list:

0 Time remaining: The time remaining in milliseconds when a choice was selected, or when the respondent left the field. You can use this to determine how long it took for the respondent to select a choice.

1 Timestamp: The Unix time when the respondent when a choice was selected, or when the respondent left the field. This is mainly for internal use, and it is unlikely you will need it.

2 Correct: Only used if the correct parameter has a value. This has a value of 1 if the choice selected is correct, and 0 otherwise. Alternatively, you can also calculate if the response is correct or not by checking the field value, which is demonstrated in the sample form.

Note: If the field is not timed, then the metadata will simply have a value of 1 if the field was opened (whether or not it was answered), and it will be blank otherwise.

How to use

Getting started

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:

  1. Download the sample form from this repo.
  2. Download the crops_list.csv (downloads as ZIP file you can attach directly to your form).
  3. Download the timed-categories.fieldplugin.zip file from this repo.
  4. 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.

Setting up the choice list

All choices in the choice list, except for the last choice, 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 it.

The last choice will not be displayed as a column, and instead it will be the "pass" value. It will be automatically selected if time runs out before a choice is selected. This "pass" choice is needed even if the field is not timed.

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

All parameters are optional, but they can be used to customize the field plug-in.

Main parameters

These are by far the most common parameters you will use.

Name Description Default
duration

How long the respondent has to answer the field until it automatically moves on to the next page. No matter the value of unit, the duration should always be defined in seconds. If time runs out before a choice is selected, then the "pass" value will be automatically selected and saved as the choice value.

If this is undefined, then the field will be untimed, and the timer will not appear.

 None
unit

Unit to be used for the display time. For example, if duration has a value of 5, and unit has a value of 'cs' for "centiseconds", then the time will start at 500, and count down to 0 over five seconds (500 centiseconds)

You can use 's' (seconds), 'ds' (deciseconds), 'cs' (centiseconds), or 'ms' (milliseconds).

 's'
correct

If a field has a "correct" value, you can define that in this parameter. 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 e, then this parameter should have a value of 'e'. Then, if the choice with a value of e is selected, then the selected choice will turn green; if another choice is selected, it will turn red.

This parameter is optional, so even if a field has a "correct" value, if you don't want to give immediate feedback, you can simply leave this parameter out. If this parameter is not defined, then the selected choice will turn blue, whether or not it is right.

 None

Other parameters

These are other parameters you can use in your form, but they are a lot less common. They are also all optional.

Name Description Default
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
continue

Whether or not the respondent can continue with the time they have left. For example, if the field plug-in has a duration of 10, and the respondent goes to the field, stays for two seconds, goes back to the previous field for five seconds, then returns to the timed-categories field, they will still have three seconds to answer the field.

If this parameter has a value of 0, then if the respondent accidentally swipes backwards or forwards while on the field, then the field will automatically be assigned the "Pass" value.

This parameter has no effect if the duration is not set.

 1
allowchange

Related to continue, by default, if the respondent answers a field, but they still have time remaining, then they can go back and change their answer. This can be helpful if the respondent is tapping the screen too much, accidentally answering a question before they actually get a chance to read it.

If this parameter has a value of 0, then once a field is answered, its response cannot be changed, even if there is time remaining. This is recommended if the field has a correct value, so the respondent cannot correct an incorrect response.

This parameter has no effect if the duration is not set.

 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

For a demonstration of the parameters, deploy this sample form, with the data file, this file. and the timed-categories field plug-in attached.

More tips

  • 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. However, the last choice in the choice list is always going to be the "pass" value, and not appear as a column. To make sure the last choice is always last, use the randomized(0, 1) appearance.
  • If you are going to use a unit other 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.

Default SurveyCTO feature support

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

More resources