Reference › SmartApp › Page › Section › EnumSetting
An enum setting creates an control that allows for the selection from among a list of options. Both single and multiple selections are supported. Grouped options are also supported. The options can be specified as a simple list of strings, a map of key/value pairs, or a list of OptionItems. The simplest case of specifying options as a list of strings is often the best approach:
section.enumSetting('simpleEnum')
.options(['red','yellow','green','blue'])
In this case the string values are used as both the labels and the value of the option. However if you are using the i18n localization option you can define translated strings for each of these options in the localization files. For example, the entries to provide English strings for the above setting might look like:
"pages.page1.settings.simpleEnum.options.red.name": "Red",
"pages.page1.settings.simpleEnum.options.yellow.name": "Yellow",
"pages.page1.settings.simpleEnum.options.green.name": "Green",
"pages.page1.settings.simpleEnum.options.blue.name": "Blue",
If you are not using the i18n localization framework or don't want to use it for a particular set of options you can provide option labels that are distinct from the option values by specifying the options as a map, where the map keys are the option values and the map values are the labels:
section.enumSetting('mapEnum')
.translateOptions(false)
.options({on: 'Turn On', off: 'Turn Off', noop: 'Leave As Is'})
A drawback of specifying the options as a map, however, is that the order of the options in the list cannot necessarily be controlled. To specify options in a controlled order you can specify them as a list of id/name OptionItems:
section.enumSetting('opjectListEnum')
.translateOptions(false)
.options([
{id: 25, name: '25 %'},
{id: 50, name: '50 %'},
{id: 75, name: '75 %'},
{id: 100, name: '100 %'}])
It's also possible to group options into multiple named groups in selector control:
section.enumSetting('groupedEnum')
.groupedOptions([
{name: 'primaryColors', options: [
{id:'red', name:'Red'},
{id:'yellow', name:'Yellow'},
{id:'blue', name:'Blue'}]},
{name: 'primaryColors', options: [
{id:'green', name:'Green'},
{id:'orange', name:'Orange'},
{id:'purple', name:'Purple'}]},
])
- closeOnSelection
- defaultValue
- description
- disabled
- groupedOptions
- i18nOptionGroupKey
- i18nOptionGroupOptionKey
- i18nOptionKey
- multiple
- name
- options
- required
- style
- submitOnChange
- translateDefaultValue
- translateOptions
▸ closeOnSelection(value: boolean): EnumSetting
Specifies whether this input should close on selection.
Parameters:
| Name | Type |
|---|---|
value |
boolean |
Returns: EnumSetting
▸ defaultValue(value: string | number): EnumSetting
Inherited from SectionSetting.defaultValue
Sets the initial value displayed in the setting when first shown to the user.
Parameters:
| Name | Type |
|---|---|
value |
string | number |
Returns: EnumSetting
▸ description(value: string): EnumSetting
Inherited from SectionSetting.description
Sets value displayed in the setting control. Defaults to 'Tap to Set' for most types of settings.
Parameters:
| Name | Type |
|---|---|
value |
string |
Returns: EnumSetting
▸ disabled(value: boolean): EnumSetting
Inherited from SectionSetting.disabled
Disables the ability to use the control
Parameters:
| Name | Type |
|---|---|
value |
boolean |
Returns: EnumSetting
▸ groupedOptions(groups: OptionGroup[]): EnumSetting
Sets the possible values as named groups of options
Parameters:
| Name | Type |
|---|---|
groups |
OptionGroup[] |
Returns: EnumSetting
▸ i18nOptionGroupKey(groupName: string): string
Returns the localization property file key for the specified OptionGroup name
Parameters:
| Name | Type |
|---|---|
groupName |
string |
Returns: string
▸ i18nOptionGroupOptionKey(groupName: string, optionItemName: string): string
REturnes the localization property file key for the specified grouped option property
Parameters:
| Name | Type | Description |
|---|---|---|
groupName |
string | the OptionsGroup name |
optionItemName |
string | the OptionItem name |
Returns: string
▸ i18nOptionKey(optionItemName: string): string
Returns the localization property file key for the specified OptionItem name
Parameters:
| Name | Type |
|---|---|
optionItemName |
string |
Returns: string
▸ multiple(value: boolean): EnumSetting
Specifies whether this device setting can have multiple values.
Parameters:
| Name | Type |
|---|---|
value |
boolean |
Returns: EnumSetting
▸ name(value: string): EnumSetting
Inherited from SectionSetting.name
Sets the name of this setting. Used to reference the setting value during the processing of events. Also used as part of the i18n key for translating the displayed name and description of the setting. All settings on a page must have unique names.
Parameters:
| Name | Type |
|---|---|
value |
string |
Returns: EnumSetting
▸ options(options: OptionList): EnumSetting
Sets the possible values as one list of options
Parameters:
| Name | Type |
|---|---|
options |
OptionList |
Returns: EnumSetting
▸ required(value: boolean): EnumSetting
Inherited from SectionSetting.required
Specifies that the control must be set in order to save the configuration page
Parameters:
| Name | Type |
|---|---|
value |
boolean |
Returns: EnumSetting
▸ style(value: OptionsStyle): EnumSetting
Set the style of the setting in the UI.
Parameters:
| Name | Type |
|---|---|
value |
OptionsStyle |
Returns: EnumSetting
▸ submitOnChange(value: boolean): EnumSetting
Inherited from SectionSetting.submitOnChange
Causes the page to be submitted and re-rendered any time the value of the setting is changed, rather than requiring the user to tap Next or Done. This behavior is useful when the the presence or enabled/disabled status of some settings depend on the value of other settings.
Parameters:
| Name | Type |
|---|---|
value |
boolean |
Returns: EnumSetting
▸ translateDefaultValue(value: string): EnumSetting
Inherited from SectionSetting.translateDefaultValue
Sets the initial value of the setting by passing the specified value through the i18n translation process.
You might want to use translatedDefaultValue rather than defaultValue in a case like setting the
default value of a text setting to the word "Kitchen" in the language of the user. defaultValue('Kitchen')
will set the value "Kitchen" regardless of the user's language or whether there were localization file entries
for the key "Kitchen". However, translateDefaultValue('Kitchen') will look for a localization file entry
with the key "Kitchen" and set the default to that value.
Parameters:
| Name | Type |
|---|---|
value |
string |
Returns: EnumSetting
▸ translateOptions(value: boolean): EnumSetting
Dtermines whether options are translated, which developers may want to disable if the labels are values generated by the app and already in the language of the user.
Parameters:
| Name | Type |
|---|---|
value |
boolean |
Returns: EnumSetting