Dynamic choice type

Dynamic choice type docuemntation

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

NameSupported
Many multiplicityyes
Default valuesyes
Unique flagno
Required flagyes
Indexable flagno
Sensitive flagyes
Calculated valueyes
Automatic initializationno
Calculated initial valueno
Aggregationno
Default type rulesno
Default display optionsyes

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"
}
⚠️ Both name and label must be strings. If the value is of a different type, you can easily convert it to a string using JavaScript’s built-in methods like toString() or String.valueOf()

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
NameTypeRequiredDescription
newValuestringnoThe new value to be selected.
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
NameTypeRequiredDescription
newOptionsobject[]noThe new possible options for the value.
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

OperatorSupported
equalsyes
notEqualsyes
emptyyes
notEmptyyes
likeyes
greaterno
greaterOrEqualsno
lessno
lessOrEqualsno
betweenno
currentUserFieldno

Aggregate queries

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

Available operators

OperatorSupported
sumno
avgno
firstno
lastno
minno
maxno

UI queries

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

Matching of values

PropertyDescription
Matching operatorlike
UI queries will try to match either the label or the name.

Available operators

OperatorSupported
Many valuesyes
Greaterno
Greater or equalsno
Lessno
Less or equalsno
Betweenno