The List Box lets a user pick a number (or no) options from a limited number of choices. It can be used just like a Checkbox Group but generally takes up less space.
The submitted value for this field type is a comma separated list of the selected list item values.
The List, Radio and Checkbox Fields knowledge base article has some examples of list options being generated dynamically and being updated by other fields.
Properties
| Label | Description | Type Name |
|---|---|---|
| Label | The label for this field | LABEL |
| Show Label | Whether to show the label for this field or not. This property adds/removes a class on the field's label element. The styling itself is controlled by the site's style sheet | SHOWLABEL |
| Hint | Additional information displayed alongside the field to assist the user in completing it. The value of another field can be used by adding the field's name between # characters. See Common Field Properties for more information | HINT |
| Minimum | The minimum number of items that must be selected. By default, no minimum is set | MINREQUIRED |
| Maximum | The maximum number of items that may be selected | MAXREQUIRED |
| Default | A default value for the field. Set a comma-separated list of the items (their values rather than display values) which should be selected by default. If the Select All option is chosen, all items will be selected by default | DEFAULT |
| Autocomplete | Adds a HTML autocomplete attribute to the field, which may prompt the browser to suggest relevant values for the filed, based on past or preconfigured (in the browser) values for the field. See Common Field Properties for more information | AUTOCOMPLETE |
| Error Message | The error message that will be displayed if this field fails its validation | ERRMSG |
| Error Message Function | A function that can be used to override the default error message. You can return a different message for each error type. The message can include the value of another field can be used by adding the field's name between # characters. See Error Message Functions for more information. This field has the following error types:
| ERRMSGFUNC |
| Searchable | Whether this field's value should be indexed by the search (the object collection if using the database save action and/or workflow process collection if starting a workflow process). This property is ignored if an External Type is specified for the form. In this case, the ability to search is determined by the searchable property of the type itself | SEARCHABLE |
| Size | The height of the list box in rows. If more items are chosen than the number here, the user will see a scrollbar | SIZE |
| Width | The display width of the list box. The value matches a CSS class, which actually sets the width | WIDTH |
| Grouped Options | The items in the list. Use the popup editor to set the value, display value, and optional group for each item. These values may be hard-coded (fixed) or dynamically loaded from a datasource. Hard-coded values can be entered using the grid provided on the 'Fixed' tab of the popup editor. Alternatively, they can be supplied as comma-separated values (value,display,group) via the 'Fixed (CSV)' tab, each row representing a single item in the list. Dynamically loaded values are set via the 'Datasource' tab of the popup editor. Typically, specifying the table, value, display and order by column names in the boxes provided will generate a suitable query. A custom query can be entered by expanding the 'Advanced' section; it will use any names set in the above boxes to generate a starting query. This custom query should select the value into a 'DataValue' column, the display value into a 'DataDisplay' column, and optionally the group name into a 'DataGroup' column. So, for example: Values can also be manipulated browser side using the _OPTIONDATA or _OPTIONGROUPS variables. Each list field will have two variables: <fieldname>_OPTIONDATA and <fieldname>_OPTIONGROUPS. The former is an array of arrays containing value, display text and group name. The latter is a comma-delimited list that contains the groups to be included in the list. This will normally be set to null to indicate that all groups should be included. Changing either of these variables using the setVariable() method within the Helper library will dynamically update this list field. For example: var newData = [];Note that as options are stored as a comma separated list, the values cannot have commas in them | OPTIONS |
| Options Function | A server-side JavaScript function that can manipulate the options list at the time the field HTML is generated This function will be executed server-side only. For example the following will replace any fixed or database query options with 10 numbered options: function (helper, optionData) { | OPTIONSFUNC |
| Validation Function | A JavaScript function that can be used to provide custom field validation whenever the field value changes or the form is submitted. This function will be executed client-side, provided JavaScript is enabled in the browser, and repeated server-side | VALFUNC |
| Default Function | A JavaScript function that can be used to calculate the default field value. This function is executed server-side when the field HTML is generated and is useful when the DEFAULT property is insufficient | DEFFUNC |
| Handlers | A JavaScript function that is executed client-side whenever the page loads, or the field value changes. This function is useful for modifying the values of other fields based on an entered value | HANDLERS |
| Read Only | Display the field as read only | READONLY |
| Validation | This property provides an extra level of validation by checking that the selected value(s) is one that is present in the field's optionData. The different modes allow you to set whether the value should be present in the original option data set server-side when the field was generated, or a value present following manipulation browser-side. None - No additional validation is performed Validate - When the field is generated its options are saved in a server-side variable. The submitted value is checked against this list of options and will fail validation if not present. Changes made to the option data browser-side are not available in the validation (so validation will fail if the option data is changed browser-side and one of the new options is chosen) Validate/Update - This performs validation in the same way as the "Validate" option but also includes any updates that may have been made to the option data browser-side. As such it doesn't provide complete validation (because both the value and the option data could be manipulated) but does allow some level of checking against more dynamic options No Validate/Update - No additional validation is performed but the option data, with any browser-side updates, is passed back to the server | VALIDATION |
| Enable Typeahead | If enabled users can type into the field. Chosen items are listed in the input box. see below for an example Note that this Typeahead feature does not currently meet the Web Content Accessibility Guidelines (2.2). Therefore, its use is not recommended where accessibility is a requirement | SHOWTYPEAHEAD |
| Typeahead Default Option Text | If typeahead is enabled, this text will be displayed when no options are selected | DEFAULTTYPEAHEADTEXT |
| Typeahead No Results Text | If typeahead is enabled, this text will be displayed if no results are found. It can include internationalisation tokens | NOTYPEAHEADRESULTTEXT |
| Additional Styling Modifier | An optional CSS modifier for the field. See Common Field Properties for an example | ADDITIONALSTYLINGMODIFIER |
| Documentation | Add documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an example | DOCUMENTATION |
Share this page
