Dynamic choice type

Overview #

This feature enables the specification of a set of potential dynamic values that the field can accommodate. Within the user interface (UI), users can select a value from these options using a dropdown, list, box, or switcher, depending on the chosen representation. The key distinction from standard choices lies in the inability to configure the potential values during the app builder’s field configuration process. Instead, the potential values can be defined using the JavaScript API, typically in events like "before show" or "on record change." Consequently, this field can possess varying potential values (and a distinct selected value) based on the current status of the record, the user, or any other condition.

It’s important to note that the raw value of the field will store all potential values along with the currently selected value.

Available features #

Display options #

Representation #

This determines how the field should be presented. The available options are:

• Dropdown: A dropdown containing the potential values will be displayed.
• List: A list showcasing all values will be displayed.
• Switcher: A switcher displaying all values will be shown. However, if there are numerous potential values, this might not be the optimal representation.
• Boxes: All records that can be chosen as the field’s value will be exhibited in boxes, simplifying user selection. This representation should only be used when the number of potential options is limited. Note that this representation supports a maximum of 100 records.

REST API #

Read format #

The format is a JSON containing the name of the value and the possible options for the selected value:

{
  "options": [{
      "label": "Alabama",
      "name": "AL"
    }, {
      "label": "Alaska",
      "name": "AK"
    }, {
      "label": "Arizona",
      "name": "AZ"
    }],
  "selectedValue": "AZ"
}

Write format #

To set the value, provide a JSON with the selected value’s name and the possible values as options:

{
  "options": [{
      "label": "AZ",
      "name": "AZ"
    }],
  "selectedValue": "AZ"
}

If you provide only a string, it will be considered as the selected value, and the possible values will be automatically generated with a single option using the provided string as both the name and label:

JavaScript API #

Read format #

The val() method within the wrapper will return a JSON containing the selected value’s name as well as the possible values as options:

// this will print something like
// "state: {options: [{label: Alabama, name: AL}, {label: Alaska, name: AK},{label: Arizona, name: AZ}], selectedValue: AZ}"
log('state: ' + JSON.stringify(record.field('state').val()));

The selectedValue() method within the wrapper will return a string containing the name of the value or null if no value is set.

// this will print something like "state: AZ"
log('state: ' + record.field('state').selectedValue());

The selectedLabel() method within the wrapper will return a string with the label of the selected value or null if no value is set.

// this will print something like "state: Arizona"
log('state: ' + record.field('state').selectedLabel());

The options() method within the wrapper will return an array with the potential options for the value.

// this will print something like
// "state options: [{"label": "Alabama", "name": "AL"},{"label": "Alaska", "name": "AK"},{"label": "Arizona", "name": "AZ"}]"
log('state options: ' + JSON.stringify(record.field('state').options()));

Write format #

For val(), you can provide a JSON with the selected value’s name and an array containing the potential values as options:

record.field('state').val(
  {
    "options": [{
        "label": "Alabama",
        "name": "AL"
      }, {
        "label": "Alaska",
        "name": "AK"
      }, {
        "label": "Arizona",
        "name": "AZ"
      }],
    "selectedValue": "AZ"
  }
);

You can also pass a string, and it will be interpreted as the selectedValue:

record.field('state').val("AZ");
//this value will be converted to {"options": [{"label": "AZ", "name": "AZ"}], "selectedValue": "AZ"}

The selectedValue() method within the wrapper will save a selected value and return a string containing the name of the value:

// this will save the name option "AZ" as selected value
record.field('state').selectedValue('AZ');

The options() method within the wrapper will store the potential options for the value:

// this will save the options to be used as possible values:
record.field('state').options([{
    "label": "Alabama",
    "name": "AL"
  },{
    "label": "Alaska",
    "name": "AK"
  },{
    "label": "Arizona",
    "name": "AZ"
  }]
);

Wrapper method:
selectedLabel() #

Returns the label of the current value or null if no value is set.

Returns #

string - The label of the current value.

Samples #

// prints the label of the current value of the field
// this will print something like "state: Arizona"
log('state: ' + record.field('state').selectedLabel());

Wrapper method:
selectedValue(newValue) #

Returns the name of the current value or null if no value is set.

Parameters #

Returns #

string - The name of the current value.

Samples #

// prints the name of the current value of the field

// this will print something like "state: AZ"
log('state: ' + record.field('state').selectedValue());

// this will set "AL" as selected value and it will print something like "state: AL"
log('state: ' + record.field('state').selectedValue('AL'));

Wrapper method:
options(newOptions) #

Returns an array with the possible options for the value.

Parameters #

Returns #

object[] - The possible options for the value.

Samples #

// prints the possible options

// this will print something like
// "state options: [{"label": "Alabama", "name": "AL"},{"label": "Alaska", "name": "AK"},{"label": "Arizona", "name": "AZ"}]"
log('state options: ' + JSON.stringify(record.field('state').options()));

// this will save the options to be used as possible values:
record.field('state').options([{
    "label": "Alabama",
    "name": "AL"
  },{
    "label": "Alaska",
    "name": "AK"
  },{
    "label": "Arizona",
    "name": "AZ"
  }
]);

Export/Import #

Export format #

The export format is a string representation of the selected value. For example:

// Dynamic choice configuration
"{options: [{label: Alabama, name: AL}, {label: Alaska, name: AK},{label: Arizona, name: AZ}], selectedValue: AZ}"

// the export value would be:
"AZ"

Import format #

The import format is a string representation of a JSON with the name of the selected value and its possible values as options:

"{options: [{label: Alabama, name: AL}, {label: Alaska, name: AK},{label: Arizona, name: AZ}], selectedValue: AZ}"

Queries #

For more information, please refer to the Query Language Documentation.

Available operators #

Aggregate queries #

Please refer to the Aggregate Queries Documentation for more detailed information.

Available operators #

UI queries #

Please refer to the UI Queries Documentation for more detailed information.

Matching of values #

Available operators #