bound-select

An HTML content command that produces a selection component with dynamic filtering and option grouping capabilities, with the selection setting the value of a Screen data variable.

The value attribute expression of this command should refer to a Screen data variable and resolve into a String - this String is used as the initial selection. When the screen is submitted, the currently selected option's value becomes the new value for Screen data variable or Map entry the value attribute expression targets.

The set of available options needs to be provided as a Collection. If the items within the Collection are Maps or Data items, the attributes option-label and option-grouping may used to define the how the options look to users and if they are grouped in some way.

If bound-select is evaluated in uneditable content (a composeContent command whose editable attribute is false does this), this content command's functionality changes. Its element will transform into a span that will have the resolved value of value as its text content. If option-label is defined, the key defined by the attribute is combined with the value expression and the resolved value of the combined expression is set as the text content, eg. if value is "item.relatedDocument" and option-label is "'Title'", the expression would be "item.relatedDocument.Title".

Attributes

value
Required	Value type	EL-evaluated
Yes	String	No
Defines the expression that should resolve into a property of the Collection item that this selection component is modifying. The type of the value the expression resolves into should be the same as the type of the option values.

options
Required	Value type	EL-evaluated
Yes	Collection	Yes
Defines the Collection supplying the data to serve as the selection's options. If the Collection's items are Maps or Data items, it is advisable to use the attributes `option-value` and `option-label` to define how the values and labels of the options are formed.

option-value

Required

Value type

EL-evaluated

No

String

Yes

If the option items in the options Collection are Maps or Data items, this attribute should be used to define which entry of an item provides the value of its option. The option's value is what can be set as the value of the Screen data variable specified with the value attribute. The resolved value should be a key common to all the Collection items - the value behind the key is then used as the option value.

If not defined, the item value itself is used as the value.

option-label

Required

Value type

EL-evaluated

No

String

Yes

If the option items in the options Collection are Maps or Data items, this attribute should be used to define which entry of an item provides the label of its option. The label is how the option is displayed to the users. The resolved value should be a key common to all the Collection items - the value behind the key is then used as the option label.

If not defined, the item value itself is used as the label. In this case if the item is not a String, the option label will be its String representation.

option-grouping

Required

Value type

EL-evaluated

No

String

Yes

If the option items in the options Collection are Maps or Data items, this attribute can be used to define how the options are grouped. The resolved value should be a key common to all the Collection items - all the option items with the same value behind this key are then grouped together in the selection.

If not defined, the options are not grouped.

option-display-limit

Required

Value type

EL-evaluated

No

Number

Yes

Defines the maximum amount of options the selection component will contain at a time. The component still has all the options, but only displays this many of them as according to the current filtering. A component containing very many options may suffer from performance issues, so consider setting this limit lower in case that happens.

If not defined, a limit of 100 is used.

of-repeat

Required

Value type

EL-evaluated

No

String

No

This attribute can be used to link this bound-select to a bound-repeat, allowing this command to access that bound-repeat's item values even if this command's element is not inside bound-repeat's host element. The selection will in this case display the option matching of the defined value of the currently targeted item of the repeat, switching as the targeted item changes. The resolved value of this attribute should match the bound-repeat-name value of the bound-repeat that this command should be linked to.

If this attribute is used to form the link, the value attribute expression needs to refer to bound-repeat's Collection item using the variable "item" regardless of the related bound-repeat-var.

Note that this attribute has no effect if this command is evaluated in uneditable content.

Examples

If bound-repeat is used to iterate through Salesforce query results, bound-select can be used to present the records' picklist fields for editing. The describePicklist command can retrieve the available options for a particular field. Below is a simple example of allowing Opportunity records' Stage to be changed; "stageOptions" is a Collection containing all the StageName values, possibly produced by describePicklist.

CODE

<tr bound-repeat="oppResults" bound-repeat-var="opp" bound-repeat-name="opps"><td><dyn-bound-select value="opp.StageName.value" options="stageOptions" /></td></tr>

A Collection of Maps or Data items, ie. Salesforce query results, can also be used easily as the set of options. In this case be sure to define the option-label attribute; if selecting a Contact for example, it might be better for the user to see the Contact's Name (eg. Millie Dynamoweaver) rather than the String representation of the Data item (eg. {"Id": "0030000022ZER40CR8", "Name": "Millie Dynamoweaver", "Title": "Test contact"}). With these kinds of options it is also possible to use the option-grouping attribute to group options sharing a certain field value together.

CODE

<dyn-bound-select value="i.relatedContact" options="availableContacts" option-label="'Name'" option-grouping="'Title'"/>

The option-value attribute may also come useful when the options are Data items or Maps. While in the above example the value of "i.relatedContact" is set to the selected Contact's Data item, in other cases it might be preferable to have the variable's value be set to just the Id of the record, for example. Here's the previous example, slightly modified, to demonstrate this:

CODE

<dyn-bound-select value="i.relatedContactId" options="availableContacts" option-value="'Id'" option-label="'Name'" option-grouping="'Title'"/>

For an example on the use of the of-repeat attribute, please see the examples section of bound-repeat.