bound-multi-select

An HTML content command that adds functionality to a specific kind of HTML structure within its host element, resulting in a selection component that presents available and selected options in their own containers, with buttons to move the options around. This command is similar to multi-select but with some exceptions, such as the Collections of options and selected items being able to contain values such as Data Items instead of simply Strings. The options and already selected items are also defined through Collection values rather than through the <option> elements within the corresponding <select> elements.

The value of bound-multi-select's primary attribute should refer to a Screen data variable with a Collection as its value. This Collection acts as the container of the selected options. As this Collection and the Collection defined through bound-multi-select-options are linked in that their items can be moved between them, please ensure that both Collections start out containing values of the same type (eg. Data items), or one of them being empty.

This command requires certain HTML elements to exist within its host element. These are as follows:

A <select> with the class "dynBoundMultiSelect-options". This element should be empty, as this command itself generates all the option elements.
A <select> with the class "dynBoundMultiSelect-selected". This element should be empty, as this command itself generates the elements for selected items, if needed.
A <button> with the class "dynBoundMultiSelect-add". Pressing this button moves the currently selected item in the Collection of available options into the Collection of selected options.
A <button> with the class "dynBoundMultiSelect-remove". Pressing this button moves the currently selected item in the Collection of selected options into the Collection of available options.
(Optional) A <button> with the class "dynBoundMultiSelect-up". Pressing this button moves the currently selected item in the Collection of selected options up one step ie. the item's index in the Collection is swapped with the item preceding it.
(Optional) A <button> with the class "dynBoundMultiSelect-down". Pressing this button moves the currently selected option in the container of selected options down one step ie. the item's index in the Collection is swapped with the item following it.

The specified elements may exist anywhere within the command's host element - they can, for example, be placed inside a table. If any of the four required elements is missing, the command reports it as an error.

Secondary attributes

bound-multi-select-options

Required

Value type

EL-evaluated

Yes

Collection, Data Item

Yes

This attribute defines the set of options from which users can select. The resolved value is expected to be a Collection, or a Data Item - in case of the latter, the command will behave as if the resolved value as a Collection containing that single Data Item.

Each item of the resolved Collection value will become an option; use the bound-multi-select-option-label secondary attribute to define how the options appear on the Screen.

bound-multi-select-option-label

Required

Value type

EL-evaluated

No

String

Yes

If the option items in the bound-multi-select-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.

Examples

Here is an example table structure with bound-multi-select in it. This selection uses the variable "selectedUsers" as its Collection of selected items and has the Collection "users" as its set of options, which would be a Collection of Data Items representing Salesforce Users. The options are displayed as email addresses, as the dyn-bound-multi-select-option-label attribute defines that the Data Item's "Email" entry is used as the label.

CODE

<div dyn-bound-multi-select="selectedUsers" dyn-bound-multi-select-options="users" dyn-bound-multi-select-option-label="'Email'"><table><tbody><tr><td><select id="dynMultiSelectOptions" class="slds-select dynBoundMultiSelect-options" size="10"></select></td><td><button type="button" class="dynBoundMultiSelect-add">Add</button> <br /><button type="button" class="dynBoundMultiSelect-remove">Remove</button></td><td><select id="dynMultiSelectSelected" class="slds-select dynBoundMultiSelect-selected" size="10"></select></td></tr><tr><td /><td /><td><button type="button" class="dynBoundMultiSelect-up">Up</button><button type="button" class="dynBoundMultiSelect-down">Down</button></td></tr></tbody></table></div>

Note that if this bound-multi-select would be accompanied by a bound-repeat whose primary attribute value is "selectedUsers" as well, adding, removing and moving items within the multi-select would be altering that repeat's output. This is because they are modifying - or bound to - the same Collection Screen data variable. This can be used to provide an alternate way to modify bound-repeat's Collection, as bound-multi-select may provide a better modification interface in some use cases. However, be sure to disable bound-repeat's "Add" and "Remove" controls, or hide the controls altogether, as bound-multi-select cannot keep its Collections of options and selections synchronized if other commands modify the latter.

Here's an example bound-repeat that could work together with the bound-multi-select above, presenting the selected users with their email addresses:

CODE

<table><thead><td>Email</td><td>User</td></thead><tbody><tr dyn-bound-repeat="selectedUsers" dyn-bound-repeat-var="user" dyn-bound-repeat-disabled-controls="add;remove"><td dyn-bound-content="user.Email"></td><td dyn-bound-content="user.FullName"></td></tr></tbody></table>