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.
radioClusters (Optional) If the radio-vertical style is used, add labels and explanation text between options. Useful for clustering options in a single element. See below for structure.
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 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.

radioClusters option

The radioClusters option allows a single choice element to contain multiple clusters of options. This is useful when there are several categories of choices, but they’re all mutually exclusive.

    "radioClusters": [
        {
            "label": "Cluster label",
            "explanation": "Explanation of what's in this cluster",
            "values": ["carrots", "onions", "potatoes"]
        },
        {
            ...
        }
    ]

The radioClusters property is an array of labels & explanations which are added in-between choices in the radio buttons.

The values property is a list of values that will trigger the display of the cluster label. It will only be displayed above the first matching value. This is so that where the list of choices may change (using instance choices), you can specify all the possible values.

For clarity in the display in the document version of the form, it may be best to use the heading property to describe the element, omit the label and explanation properties from the element itself, and use an entry in the radioClusters option to display the label above the first choice.

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.