choice-field
The choice-field component allows you to select one or more options from a predefined list. This enhances user experience by providing a straightforward way to make selections, such as choosing a setting, selecting a category, or picking an item from a list. Implementing a choice-field component involves defining the available options and efficiently handling the user's selection.
Benefit: Using the choice-field component over the checkbox component eliminates the need to use numerous checkboxes and complex expressions to achieve the same outcome.
Core structure for choice-field | |
instanceId | The unique identifier for the choice-field component. |
label | Provide a label/name for the choice-field. |
data | Use an expression that evaluates to an array of options. |
item | The item property uses the component of choice-field-item that includes: title and value. |
Other options | |
errorText | Add text, string, or expressions to show text under the choice-field indicating an error/invalid value in the field. Text is shown in isNegative (red) styling. |
helperText | Add text, string, or expressions to guide users by showing text under the choice-field. Helper text is displayed only when there is no errorText. |
initialValue | The initialValue is the value that will be displayed in the choice-field when the form is initially loaded. You can use this property to preset the choice-field with a default value so that you do not have to manually select it, for example, on a yes/no choice the initial value can be set to no. |
isHidden | If true the choice-field will be hidden on the form. If set to false the field will be shown. |
isIgnored | When true, the field will be ignored when submitting the form and the content will not be stored. |
isMultiple | Set to true allows you to select multiple items inside the choice-field. Set to false only allows a single selction in the choice-field. |
isOptionalLabelHidden | If the field is optional you can turn off the "(optional)" label by setting this field to true. This property works in combination with isRequired: false. |
isRequired | Set to true when the field is required. Useful when you use it in form submission. Set to false the choice-field is optional and will have (optional) in the label. |
itemsPerRow | Number of choice boxes to show in each row. |
nextProperty | Name of the property you want to focus next in the form when you use return/next on a keyboard. |
style | isDisabled - disables the choice-field preventing the selection of any of the choice-fields. |
value | The value that the choice-field will output as its state. |
Other options for choice-field-item | |
instanceId | The unique identifier for the choice-field-item component. |
title | Text displayed on the choice-field item. You can add text, expressions or Text with Format in the field. Text with format includes, currency, decimal, dateTime and more. In most instances an expression similar to [email protected] is used to reference the datasource. |
value | The value of the item. It has to be unique for each item and is usually the ID of the record from the datasource. |
Actions | |
onChange | The action is triggered when the content in the choice-field-item is changed. Use IntelliSense (ctrl+space) to see the list of available actions. |
State Configuration | Key | Notes |
selected value |
| |
activeItemId now |
|
- The choice-field is an input control.
- Only text can be displayed in the title property.
Choice-field with single selection
In this example, a choice-field component is configured with basic Yes/No options. If you a new customer and select Yes, then a when property is used with an expression to display additional form fields for the customer to complete. If you an existing customer, select No and click the Register & place order button to goTo the product-item to place an order.
Examples: See the full example in GitHub.
Choice-field with multiple selection
In this example, two choice-field components are used. The first is a single Yes/No selection to answer a question. The second choice-field is configured with a when property to only display is the Yes selection was made. The isMultiple property set to true allows multiple options to be selected in the component. Selecting submit uses an info-modal to show the form was successfully submitted.
Examples: See the full example in GitHub.
Loading of multiple selected options
In this example, we want to load the patient's form that they completed in the example above, and show their selected details and allergies. Each patient can have multiple allergies, and the data would be saved as an object in the database. To deserialize the object the jsonProperties property is configured with the column containing the object of multiple allergies. In the choice-field component the intialValue is then configured to return the selected allergies for the specific patient. The execute-entity action is configured to update the patient data.
Choice-field with 3 items per row
Using the itemsPerRow property in the choice-field component defines how many choice option items must be shown on each row. Keep in mind this is on a mobile device, having more than 3 could make the options hard to read.
Examples: See the full example in GitHub.
Choice-field with an initial selection
In this example of the choice-field component the form opens with an option already selected. This is configured using an expression in the initialValue property. You can change the property. Note that the onRefresh event used to reset the form, resets the choice-field back to it's orginial state with the initialValueselected.
Examples: See the full example in GitHub.
Choice-field with onChange
In this example, when the choice-field-item is selected and onChange event triggers a open-url action providing the information on the holiday packages.
Examples: See the full example in GitHub.
