Multi Select

Multi Select allows users to select multiple items at a time from a list of items.

Data binding

Set or modify the data binding for the control in the General properties tab. The control can be bound to an ANY (List) type.

Configuration properties

Set or modify configuration properties for the control, such as appearance and behavior properties, in the Configuration properties tab.

Screen size: A configuration property that has the Screen Sizes icon beside the property name can have different values for each screen size. If you do not set a value, the screen size inherits the value of the next larger screen size as its default value. If you are using the Process Designer desktop editor (deprecated), you are setting the value for the large screen size. The other screen sizes inherit this value.

Theme definitions: Theme definitions specify the colors and styles for a control and determine the appearance of the control. You can preview the look and feel of controls in the theme editor. See Themes.

The appearance configuration properties for the Multi Select control are shown in the following table:

Table 1. Appearance configuration properties for Multi Select
Appearance configuration property	Description	Data type
Width	The width of the control. You can specify the width in px (pixels), % (percent), or em units. For example, 50px, 20%, or 0.4em. If a unit type is not specified, px is assumed.	`String`
Size	The size of the text in the control, the size of the label text, and the amount of padding around the text. For example, to make the text and label more readable on smart phones, you can set this configuration option to `Large` to compensate for the small screen size.	`String`
Label placement	The label placement locations for the control.	`String`
Label width	The width of the label. You can specify the width in px (pixels), % (percent), or em units. For example, 50px, 20%, or 0.4em. If a unit type is not specified, px is assumed.	`String`

The behavior configuration properties for the Multi Select control are shown in the following table:

Table 2. Behavior configuration properties for Multi Select
Behavior configuration property	Description	Data type
Tab index	The tabbing sequence index. The tab indices start at 1 and may be set sparsely. For example, you can use 1, 5, 10.	`Integer`

The items configuration properties for the Multi Select control are shown in the following table:

Table 3. Items configuration properties for Multi Select
Item configuration property	Description	Data type
Item lookup mode	The method used to populate the list of items that the user can select from. Note: Make sure the correct option is selected, otherwise the list will not be populated correctly. Start Empty Programmatically populate the selection list using the `appendItem(value, displayText)` method. Items From Service The selection list is populated from a service that you specify in the List items service option. Items From Static List The selection list is populated by properties that you enter in the Static list option. Items From Config Option The selection list is populated from a business object list that you specify in the Item input data option.	`String`
List items service	The service used to populate the list of items that appear in the selection list. The service is used when the Item lookup mode is Items From Service. The service is a service flow with appropriate Ajax access that provides the selection list based on the data provided by the Service input data business object. You can use this option as an alternative to binding the control to a list object.	Service flow
Service input data	A business object that provides the input data that is passed to the service flow that populates the selection list. This option is used when the Item lookup mode is Items From Service.	ANY
Item input data	A business object list that populates the selection list. This property is used only if the Item lookup mode is Items From Config Option.	ANY[]
Item selection data	In the Display property field, set the business object property to display in the selection list. If no values are specified for the data mapping properties, the default values are `name` for Value property, and `value` for Display property.	`SelectDataMapping`
Output business data	When the control is bound to a complex type, the property that the user selects is passed to the property specified in Display property and to the property that is bound to the control.	`SelectDataMapping`
Static list	A static list of items to populate the selection list. Use this option only for a static list. Do not specify a variable for this option. For a variable list, use the Items From Config Option lookup mode.	NameValuePair[]

Example: Items from a static list

You have a Multi Select control with the label Grocery list and the Item lookup mode that you selected is Items from static list. In the Static list, you defined the following name value pairs.

Table 4. Static list
Name	Value
1	Milk
2	Bread
3	Bananas
4	Rice

You will see the following result:

Example: Populating items by using a business object

This example uses a Customer business object to populate a list of first names in the selection list. When the user selects multiple names, the corresponding record is displayed in a table.

The Customer business object has the following structure:

An ID parameter of type String.
A firstName parameter of type String.
A lastName parameter of type String.

The Customer business object has the following default values:

var autoObject = [];
autoObject[0] = {};
autoObject[0].ID = "000";
autoObject[0].firstName = "Pierre";
autoObject[0].lastName = "de Fermat";
autoObject[1] = {};
autoObject[1].ID = "001";
autoObject[1].firstName = "Isaac";
autoObject[1].lastName = "Newton";
autoObject[2] = {};
autoObject[2].ID = "002";
autoObject[2].firstName = "John";
autoObject[2].lastName = "Venn";
autoObject

The client-side human service has a private variable outputList of type Output[]. The Output type has two string parameters, value1 and value2. The Multi Select control is bound to outputList, which contains the data output of the control.

The coach has a Multi Select control with the following properties:

Under General, set Binding to outputList.
Under Configuration > Items, set Item lookup mode to Items From Config Option.
Under Configuration > Items, set Item input data to Customer[].
Under Configuration > Items > Item selection data:
- For Value property, specify ID.
- For Display property, specify firstName.
Under Configuration > Items > Output business data:
- For Value property, specify value1.
- For Display property, specify value2.

The Table control has the following properties:

Two columns titled Value1 and Value2
Under General, Label is set to Output List.
Under General, Binding is set to outputList[].

Tip: To create the table quickly, drag the outputList variable onto the coach.

This is the result that you get when you run the coach:

Image showing a selectable list and a table with two columns titled Value1 and Value2

This is the result after you make multiple selections:

The values that you select are displayed in the Value2 column, which is the property that is specified in the Display property option under Output business data. The property is passed by value. If you enter Value1 as the Display property, the names that you selected appear in the Value1 column.

Events

Set or modify the event handlers for the control in the Events tab. You can set events to be triggered programmatically or when a user interacts with the control. For information about how to define and code events, see User-defined events. The Multi Select control has the following types of event handlers:

On load: Activated when the page loads. For example:
console.log(me.getItemCount());
On change: Activated when the bound data changes. For example:
${MultiSelect2}.reloadServiceItems(me.getSelectedIndices());
On service items: Activated when the service flow returns an item list. Activated only if Item lookup mode is set to Items From Service.
console.log("MultiSelect1 item service retrieved items successfully");
On service error: Activated when the service flow returns an service error. Activated only if Item lookup mode is set to Items From Service
me.clearItems();

Depending on the specific event, you can use JavaScript logic to modify the effects of the control. More information on using events with controls is found in the topic User-defined events.

Methods

For detailed information on the available methods for Multi Select, see the Multi Select JavaScript API.

Additional resources

For information about how to create a coach, see Building coaches.
For information about standard properties (General, Configuration, Positioning, Visibility, and HTML Attributes), see Coach view properties.