Choice type

Overview #

This feature enables you to define a predefined set of values that the field can contain. Within the user interface (UI), the user can select a value from the provided options using a dropdown, list, or switcher, depending on the chosen representation.

Each of the potential values comprises a label and a name, with only the name being stored in the database.

Available features #

Type rules #

Values #

These represent the potential values that can be assigned to the field. For each of these possible values, the following properties are available:

• Label: This is the string displayed to the user.

• Code: This is the value stored in the database and utilized by the REST and JavaScript APIs.

• Color: This denotes the color assigned to the choice. The color chosen is sensitive to the current theme.

• Condition: This allows you to define a conditional expression to determine the availability of this option. The available options include:

  • None: The option will always be available.
  • Expression: The option will be accessible only if the expression evaluates to true. For more information, consult the Expressions documentation.
  • Script: The option will be accessible only when the script evaluates to true. The script’s context is as follows:

  ---

  Parameters #

  Name	Type	Description
  record	sys.data.Record	This refers to the record associated with the operation. If the field is within an entity field, this record will be the one containing the field. In the case of the field being an action parameter, this record will correspond to the record where the action is being executed.
  parentField	sys.data.Record	This variable is only accessible when the field is situated within a nested field, and it is contingent on the source variable being either a record or an action (the same principles apply when it is an action parameter or an entity field). It is a sys.data.Record object with the distinction that the root of the record is established as the nested fields containing it. This configuration enables you to access fields within the nested group using the syntax parentField.field('fieldA') instead of record.field('nested.fieldA') or action.field('nested.fieldA'). This distinction is particularly valuable when nested fields are multi-valued, as you are not required to ascertain the index.
  action	sys.data.Action	This variable will be accessible solely when the field functions as an action parameter. It grants access to other parameters.

  Returns #

  boolean - You should return true if the option is available, and false otherwise.

  Samples #

  // option will be available only if 'name' starts with 'test'
  return !record.field('name').isEmpty() &&record.field('name').val().indexOf('test') == 0;
  

  
  

  ---

Display options #

Representation #

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

• Dropdown: A dropdown containing the possible values will be displayed.
• List: A list showing all values will be displayed.
• Switcher: A switcher displaying all values will be shown. However, if there are numerous possible values, this might not be the optimal representation.

REST API #

Read format #

The format is a string containing the name of the value:

"state": "active"

Write format #

To set the value, provide a string containing the name of the value:

"state": "inactive"

JavaScript API #

Read format #

The val() method within the wrapper will return a string containing the name of the value:

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

The label() method within the wrapper will return a string containing the label of the value:

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

Write format #

You should provide a string with the name of the value:

record.field('state').val('active');

Wrapper method:
label() #

The label() method 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
var record = sys.data.findOne('tasks', {number: 1});
log('status label: '+record.field('status').label());

Export/Import #

Export format #

The export format is a string containing the name of the value:

"choiceField1","choiceField2"
"active","inProgress"

Import format #

The import format is a string containing the name of the value:

"choiceField1","choiceField2"
"active","inProgress"

However, it will also accept the label of the value:

"choiceField1","choiceField2"
"Active","In Progress"

It will first attempt to match by name. If there is no match, it will then attempt to match using the label. In both cases, the matching process is case-insensitive.

Queries #

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

Available operators #

Query formats #

You should provide the a string with the name of value. For instance:

// finds active companies 
var records_sample = sys.data.find('companies', {'state': 'active'});
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds active companies 
var query_sample = sys.data.createQuery('companies')
    .field('state').equals('active')
var records_sample = sys.data.find(query_sample);
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds active companies 
GET /data/contacts?state=active

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 #