Choices Field Type

TABLE OF CONTENTS

The choices field allows for single or multiple-choice selection via a drop-down, checklist or text search. The field is kind of like a Swiss Army Knife: a multi-purpose field that can display sets of choices in a variety of ways. As such, Choices fields have a large number of properties that allow you to configure the field.

Basic Properties

Data Name

This is the name of the field that should be referenced in any form logic or API calls. Users will not see this name on the form.

Data names cannot contain spaces or any special characters other than an underscore and must begin with a letter. They are case-sensitive and must be referred to precisely whenever they are referenced.

Title Text

This is the name of the field that will be displayed to users on the app. This property is completely optional; while a field must contain a data name, a field title is optional.

The text color may be chosen with a hex code. The text may be also formatted as Bold or Italic and given a relative size -- Small, Medium (the default) or Large.

Hint Text

This optional field can be used to show secondary information to the user in the app. Consider using this to provide instruction or clarification to the user as they make a selection.

Formatting options for this property are the same as those given available for the Title Text property.

Display Style

This controls how your Choices field will appear to the app user. There are three options from which to choose:

  • Drop Down List is a compact single-line entry that opens a listing of choices for selection.
  • List of Choices shows each option available with a checkbox when the layout is Vertical. For Horizontal layouts, each option shows as colored buttons labelled with the option text.
    Also allows display of additional row information if you use a Data Source for your answer choices. This additional display is configured via the Default Display field found on the Settings page of all Data Sources.
  • Auto-Complete shows a search box that then shows filtered results as the user types.

NOTE: Please see "Auto-Complete Threshold" below in this article for more info.

Answer Choices

This provides two options controlling the actual choices shown to the app user.

  • To input options manually, choose Static List. You will then need to provide the set of options which will be embedded into your Form design.
  • Alternatively you can autoload the choices from a Data Source. This more powerful approach lets you reuse your option list across fields/Forms. You can also filter the options shown and even bind other fields to Data Source columns.
  • Display/Value Columns

    By default, the first and second columns of your chosen Data Source will be used as the answer value and the displayed row text, respectively. The answer value is the column value stored in this field when the user selects a row; the field will only show the unique set of values found in this column. Both this and the display column can be changed in this dropdown, however, to use other column values as your answer and display text instead. Note that if you do so, the app will automatically use only the unique set of possible values found in the given column - i.e., there will be no duplicate options shown to the user.
  • Sort Order

    This dropdown determines the sort order for values from the data source when listed in the choices field. When this dropdown is set to Default, options will be sorted according to the order specified on the linked Data Source's Settings page. All other Sort Order values override the data source defaults when sorting this field's options.
  • Filter Rows

    This allows you to dynamically control the rows to be displayed in the choices field using fixed criteria or a formula.
    • Formula
      Click "use formula" and enter a formula into the resulting field to define a formula for filtering content from the data source. Click the hammer icon in the upper-right of the field to enter the formula builder.


      For syntax, refer to rows via {{this[column]}} -- 
      e.g., {{this[2]}} > {{myfield}} shows rows where the 3rd column is greater than the value in "myfield."

      To filter previous answers out of a repeated Choices field's options, use a formula of:
      NOTIN({{this[0]}}, PRIOR('choicesfield'))
      The column number in brackets should correspond to the column used as the Value Column.

    • Criteria
      Click "use criteria" to choose one or more fields within the form that will be used to filter content from the data source. More criteria can be added by subsequently clicking "add criterion."



      The "in list" operators match columns against comma- or pipe-delimited values, while the "expression" filter matches columns against a regular expression value. More information about regular expressions ("RegEx") can be found here.
  • Allow Form Fields to Modify Data Source

    This option allows for data source rows to be created/edited. Modification will be done for each value brought into the form via other form fields that have a data source column linked via their respective "Bind to Data Source Column" properties. For a detailed recipe on how to use this functionality, please refer to this article.
    If you check Create/Update or Delete Row, please head over to this data source and ensure you have added a row with the first column value set to 0. This "dummy row" will be used by the app to create new rows. Also ensure you have checked the Is Unique column in the column's Advanced Settings so that Updates or Deletes to this data source are only performed against unique rows.

Option Colors

These boxes feature five colors corresponding to the first five choices on a choices field set to Horizontal display. These colors can be changed by either selecting a new color from the color picker or entering a hex color code.

Tip: when choosing a color to edit, lower the mouse cursor into the desired color box from above (please see animation below).

Option Background Color

The color chosen in the hex code field here will apply to the background color of choices, but only when the field is in Horizontal layout. The Transparent box can also be chosen instead for making this transparent instead of a solid color.

Multiple Choice

Checking this checkbox allows for multiple choices to be selected rather than just one.

Layout & Styling

Field Layout

This drop-down determines how this field is shown on the screen.

  • Vertical places the Title and Hint vertically above the choice field.
  • Horizontal will stack the choices to the right of the Title and Hint text.
  • Horizontal (Tablets Only) will use Vertical layout for phones and Horizontal for tablets.

Background Color

The color chosen in the hex code field here will apply to the section field. The Transparent box can also be chosen instead for making this transparent instead of a solid color.

Collapse Options on Select

When this checkbox is checked, the app will automatically hide all other options on the choices field once the user makes a selection. If the user deselects their chosen item, the hidden options will reappear. This does not apply if the field is using the Drop Down display style.

Auto-Complete Threshold

The figure in this drop-down determines the threshold at which the app will automatically apply the auto-complete search display type for the choices field. When the option count exceeds this value, the auto-complete display type will be shown instead of the display type selected in the Display Type property of the choices field (see above in this article). This is to ensure good performance with very large lists of options -- e.g., product catalogs.

The maximum threshold depends on the chosen Display Style. The maximum for Drop-Down List is 500 while the maximum for List of Choices is 50. The display type will be set to auto-complete whenever the number of available choices (after all filters have been applied - see above in this article) exceeds this maximum threshold.


Auto-Complete Search Pattern

This option allows you to specify a replacement regular expression for row matching, rather than the default behavior where the user's search query will match anywhere within the displayable row values.

Use {{this}} to refer to the user search text in your regular expression -- e.g., "^{{this}}" will show rows that start with the search text.

Use "{{this[X]}}" (where X is a zero-based index) to refer to a specific space-separated term in the user search text. For instance, for the search text "search text," {{this[0]}} will be replaced with 'search' and {{this[1]}} will be replaced with 'text'. E.g., {{this[0]}}|{{this[1]}} will show rows that contain either term 0 or term 1. Or, "(({{this[0]}})+.*({{this[1]}})+)|(({{this[1]}})+.*({{this[0]}})+)" will show rows that contain both term 0 and term 1.

Placeholder Text

Text entered into this property defines the hint text shown inside the field's answer box. If this is left blank, then defaults to "Enter keyword..."

Validation & Behavior

Required

Checking this box will enforce validation against this field to make the field required, disallowing the user from progressing to the next page or submitting the form if it is left blank. If the user tries, they will be prompted with an error to return to the field and enter a value. When this validation occurs is determined by the "Validation Property" chosen on the page level; please see this article for more detail on this.

This property can also be made conditional based on a formula. To enable this, click "add condition" below the checkbox and enter a formula into the field that populates. The formula serves as the basic of the required-ness of this field.

Please see this article for more information on conditionally-required fields.

Visibility

The contents of this field will determine whether the field will be visible to the user. For more detail on visibility rules, please see this article.

Dynamic Value

This property is used to define a calculation/formula that will populate the field's value. Often this is used in conjunction with the "Read Only" property (see below) so that the field will calculate and display to the user without the possibility of manual edits. This article is recommended as a starting point for more reading on this.

Please see this article for details on the relationship between Default Value and Dynamic Value.

Read Only

If this checkbox is checked, users will be able to see the contents of the field but will be unable to make edits.

Similar to the Required property, the Read Only property also includes the ability to define a conditional formula determining whether the read-only property is enabled. Click "add condition" to define such a formula.

Custom Validation

Add your own custom formula to this property for validating choices made in this field by users. The formula is only applied when the field has an answer. Enforcement will be done according to the "Validation Property" chosen on the page level; please see this article for more detail on this.

Validation Message

The contents of this property will serve as a custom message to display to the user if their input fails validation.

Advanced Options

Default Value

The value entered in this property serves as the initial value of the field prior to manual input/selection. Please see this article for details on the relationship between Default Value and Dynamic Value.

Bind to Data Source Column

This property allows for the binding of the contents of the field to a linked data source. For details, please see the screenshot below:

  1. The data source can be selected with this dropdown. More than one will be available if multiple data source control fields (choices fields or data fields) have been added to the form.
  2. The data source control field can be selected from this dropdown. More than one will be available if multiple data source control fields for the same data source have been added to the form.
  3. The column on the data source to be bound can be selected from this dropdown.

Data Source binding allows you to create forms that can load data from, and update data to, any given data source. This opens up amazing opportunities to have dynamic data that is updated on the move (e.g., adding contacts or clients). For more information, please see this article.

Bind to Global Value

Global Values are a local key/value store that is available to any Screen on the app. Use this property to allow the user to view and save defaults for use across the app (e.g., a default project or customer). Please see this article for more information.

Exclude from Export/Display

By default, every field is displayed on Form entries in the Data area, and is included in non-templated exports (e.g., generic pdf, CSV, spreadsheet, database connectors). Use this property to prevent this field from showing on all such display and exports.

Is Personal Data

Indicates that data captured in this field may contain personal or sensitive data, which in turn can be anonymized when exported from the platform when then the "Anonymize Personal Data" option is checked on a form connector. Please see this article for more on this. 

NOTE: Use of this option does not grant or imply additional security, protection and privacy of data.

Barcode Lookup

If this checkbox is checked, the user can scan a barcode for the the app to automatically look up in the available choices.

Always Show Default Option

When this checkbox is checked, if Default Value is set, the matching option will always show, regardless of filters.


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.