select_one with "quick" appearance

Use this field plug-in when there should be a time limit for responding to a select_one or select_multiple question. The user will only be able to answer this question within a certain number of seconds after first arriving at the field. For example, if they leave the field while there are 15 seconds remaining, then come back 5 seconds later, there will be 10 seconds remaining on the timer.

• Enforce a time limit on a field
  Specify how long a user is allowed to spend answering a question. The default is 10 seconds, but you can choose your own with parameters.
• Enforce a time limit on a group of fields
  Use this field plug-in on multiple fields in a field list group to set a time limit for a group of questions.
• Auto-advance when time runs out
  By default, the field will auto-advance when time runs out. You can change this behavior by adjusting the parameters.
• Disallow changes after time runs out
  By default, the user will not be able to change their answer after time has run out. You can change this behavior by adjusting the parameters.
• Disallow changes after a selection has been made
  By default, the user will be able to change their answer as many times as they wish until the time runs out. You can change this behavior by adjusting the parameters.
• Specify the value to use for missed or passed answers
  By default, this field plug-in will choose -99 as the answer when the time runs out. You can change this behavior by adjusting the parameters.
• Customize the countdown timer appearance
  • Choose which time units to show in the countdown timer.
  • Hide the countdown timer entirely.

This field plug-in works with the select_one or select_multiple field types, and will return the choice value(s) of the selected choice(s). A field value is not set until either a choice is selected, or time runs out.

Please note: by default, this field plug-in will attempt to select the choice value -99 when the time runs out, so you should be sure to include a choice in your choice list that has a value of -99 (this choice will be hidden by the field plug-in). You can choose a different value to use with the pass parameter.

This field plug-in stores the remaining time for the field in the field's metadata. You can use this if you would like to know how much time was left when the user left the field. If the advance parameter has a value of 1, then the time they left the field will also be the time a choice was selected. The metadata will be a space-separated list of two items: the milliseconds remaining (regardless of the value of the unit parameter), and the Unix time when the user left the field.

So, if you would like to know how much time is remaining for a field named fieldname, use this expression in your SurveyCTO form:

selected-at(plug-in-metadata(${fieldname}), 0)

For example, if the user left the field when there was 11,536 milliseconds remaining, then the above expression will return 11536. To learn more about how this expression works, check out our documentation on using expressions.

If you would like to display this value in a field in the form, it is a good idea to use that expression in a calculate_here field. With normal calculate fields, the plug-in-metadata() function cannot get the metadata until a value is set for the field with the field plug-in, and it will not be updated until the form is saved-and-closed. By making the field a calculate_here field instead, it will update whenever you pass by that field. That way, if the enumerator goes back-and-forth in the form (either on purpose or accident), the time remaining displayed will be accurate, updating when needed.

This is demonstrated in the field list at the end of the sample form. To try it out, go to that field list, swipe ahead to view the time remaining in the note field after the field list, and then swipe back to continue working on the field, and the time remaining in the note field will update each time you swipe to it; you can keep trying this to see the time update. The time in the note field will not update live (i.e. it will not count down), but it will store the latest time remaining since you were last on the field with the timer.

If the time remaining will not be displayed in the form, or if the form is set up to be more strict when the enumerator can move forward, then it is better to use a normal calculate field instead.

1. Download the sample form from this repo and upload it to your SurveyCTO server.
2. Download the timed-choice.fieldplugin.zip file from this repo, and attach it to the sample form on your SurveyCTO server.
3. You can use the sample form as-is, or adjust the parameters to change the behavior (see below).

There are many available parameters to help you customize this field plug-in, but all of them are optional. Most likely, you will only need to set the duration parameter. Feel free to leave out the other parameters if their default settings work well for you.

Make sure they are in single quotes, exactly as shown above.

The default behavior of the advance parameter has an exception: if the disp parameter has a value of 0 (i.e., the countdown timer is hidden), then the field will not auto-advance by default. See the table below for expected behavior:

This is because timers are usually hidden in field lists so that multiple versions of the same timer are not displayed. By also turning off the auto-advance, it ensures there are not multiple calls to move to the next field, which can cause the form to skip too far ahead.

If you would like the field to move forward after 20 seconds, you can use this in the appearance column of a spreadsheet form definition:

custom-timed-choice(duration=20)

If you would like the time to be displayed in milliseconds, you can use this in the appearance column of a spreadsheet form definition:

custom-timed-choice(duration=20, unit='ms')

If you would like your select_one field to have the quick appearance, and the field duration should be 15 seconds, you can use this in the appearance column of a spreadsheet form definition:

quick custom-timed-choice(duration=15)

For more examples, check out the sample form.

In order to show a group of questions all on the same screen, with one countdown timer at the top that applies to all of them, you can create a field list group with many select_one and/or select_multiple fields, and use this field plug-in on each of them. While this is possible to do with this field plug-in, you should also consider using our timed-field-list field plug-in, which is better-suited for this use case. Here are some things to keep in mind when using this field plug-in with field lists:

• Except for the very first field in the field list, each field should have disp set to 0. That way, the timer only appears in one place, at the top of the screen.
• All fields should have the same duration value. To make sure of this, it may be a good idea to store the duration value in a separate calculate field, and then reference that value in the parameters of each of your field list fields.
  For example, you could create a calculate field named duration_for_timed_field_list with a default value of 30. Then, in the appearance column of each field in your field list, you could put custom-timed-choice(duration=${duration_for_timed_field_list}). That way, it is easy to keep track of and change the duration of each field in the field list.

For an example, see the group "fieldlist" in the sample form.

You can use the field plug-in for its timer only, maybe as part of a field list. Add the field to a normal select_one or select_multiple field. For the choice list, give it a single choice with a value of -99 (or whatever the value of the pass parameter is). Since the "pass" choice is removed from the choice list, it will simply show the timer, without any choices. Unless the enumerator should stay on the page until the timer runs out, make sure this field is not required, since the enumerator will not be able to give the field a value by selecting a choice.

This is demonstrated in the field list at the end of the sample form. At the top of the field list, there is a timer without any visible choices, only the hidden "pass" choice. However, when the time runs out, it will auto-advance to the next page, so the timer is effectively applied to all fields on that page, even the text field. However, if the field plug-in is not applied to all fields, it will not block the choices after time runs out, so a fast enumerator could still potentially change their response; this is why we usually recommend the method above for field lists.

• Similar alternatives
  • If you need to time a text, integer, or decimal field, use the timed-advance field plug-in.
  • You can use this field plug-in to create a timed field list (multiple fields on the same page), but also consider using our timed-field-list field plug-in, which is better-suited for this use-case.
• Sample form
  You can find a form definition in this repo here: extras/sample-form.
• Developer documentation
  More instructions for developing and using field plug-ins can be found here: https://github.com/surveycto/Field-plug-in-resources