Choice

A choice from a short fixed list, corresponding to an HTML <select> element or a group of HTML <input type="radio"> elements.

Each entry in the list of choices has an ID, which is the value stored in the document, and a display name, which is displayed to the user. They can be the same. The ID is usually a string, but if it’s detected it’s a number, it’ll be automatically converted to a number before being stored in the document.

Properties

type "choice"
style What style of choice. Defaults to "select".
radioGroups (Optional) If a radio style is used, display the options in this number of groups. Useful for displaying long lists of options.
prompt For the "select" style, the text to use for the null ‘choice’, displayed first in the list to prompt the user to select something. Defaults to a reasonable message. Set to false to have no prompt.
choices The choices for the element. See below for how choices are specified.
objectIdProperty The property name for the ID, if applicable to the choice list. Defaults to "id".
objectDisplayProperty The property name for the display name, if applicable to the choice list. Defaults to “name”.
minimumCount (optional) The minimum number of choices required to pass validation. ("multiple" style only)
maximumCount (optional) The maximum number of choices allowed to pass validation. ("multiple" style only)

All the common properties are supported.

Style options

The style property can be set to:

"select" Use an HTML <select> element.
"radio-vertical" Use HTML <input type="radio"> elements, laid out vertically.
"radio-horizontal" Use HTML <input type="radio"> elements, laid out horizontally.
"radio" Alias for "radio-vertical"
"multiple" Use checkboxes to allow multiple choices. See the notes below for how this changes the behaviour of this element.

Specifying the choice list

The choice list can be specified in a few different ways.

Array of Strings

A simple array of strings is interpreted as a list of choices where every element has an ID equal to the display name.

    "choices": ['Choice One', 'Choice Two', 'Choice Three']

Array of arrays containing two values

An array of two element arrays, where the first element is the ID, and the second the display name.

    "choices": [
        ['one',   'Choice One'],
        ['two',   'Choice Two'],
        ['three', 'Choice Three']
    ]

Array of objects with specified properties

An array of any JavaScript object which has properties which can be used for the ID and display name.

    "choices": [
        {"id":'one',   "name":'Choice One'},
        {"id":'two',   "name":'Choice Two'},
        {"id":'three', "name":'Choice Three'}
    ]

By default, the id and name properties are used, but you can use the objectIdProperty and objectDisplayProperty properties in the specification to use different properties.

Specify a per-instance choice list

If the choice list is a String, it is interpreted as the name of a per-instance choice list. This list must be provided to every instance using the choices() function on the FormInstance object.

This is required to implement choices which are different every time the form is used, or are determined on a per-user basis.

Automatic numeric ID detection

If the choice list is an array of arrays or an array of objects (or a per-instance choice list formed this way), then, if the first entry has an ID which is a JavaScript number, then the IDs are assumed to be numeric and the value stored in the document will be a number too.

This should make the right choice every time, but can be easily overridden if not.

Restrictions

The empty string cannot be used as an ID.

Allowing multiple choices

If the style is set to "multiple", then multiple choices can be chosen. This will change the behaviour of the element:

  • The value is an Array of choices
  • The minimumCount and maximumCount properties may be specified for extra validation
  • If no choices are made, the value is empty (not the empty array, [])
  • But if minimumCount or maximumCount is specified, and validation fails, an empty array will be set if there are no choices.