Single Select

Single Select allows users to select an item from a drop-down list. You can populate the list of items statically, use a business object, or use a service to retrieve the list.

Data binding

Set or modify the data binding for the control in the General properties tab. The control can be bound to an ANY 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 Single Select control are shown in the following table:

Table 1. Appearance configuration properties for the Single Select control
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 position of the label.	`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 Single Select control are shown in the following table:

Table 2. Behavior configuration properties for the Single Select control
Behavior configuration property	Description	Data type
Tab index	The tabbing sequence index of the form control. The tab indices start at 1 and can be set sparsely. For example, you can use 1, 5, 10.	`Integer`
Placeholder	Text that is displayed before a selection is made.	`String`

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

Table 3. Items configuration properties for the Single Select control
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[]

The selection state is copied to the listSelected property in the input business object list. You can retrieve the selection by binding a control to this property. See Example: Populating items by using a list business object.

Example: Populating items from a static list

This example uses a Single Select control with the label Grocery list and the Item lookup mode set to Items From Static List

The Static list has the following name value pairs.

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

This is the result when you run the coach:

This image shows a list titled Grocery list with the items Milk, Bread, Bananas, Rice. Bananas is highlighted.

Example: Calculating totals using items from a static list

This example uses the value of the Name field in a static list to calculate the value of another field.

The Coach has a Horizontal Layout that contains a Single Select control, an Integer control and a Decimal control. The coach also has a Button control.

The Single Select control has the following properties:

General > Common > Labelis Item.
General > Common > Control ID is Item.
Configuration > Behavior > Placeholder is Select Item.
Configuration > Items > Item lookup mode is Items From Static List.
Configuration > Items > Static list has the following entries:
- Name is .50, and Value is Apple.
- Name is .75, and Value is Orange.
- Name is .25, and Value is Banana.

The Integer control has the following properties:

General > Label is Quantity.
General > Control ID is Quantity.

The Decimal control has the following properties:

General > Label is Total.
Behavior > Decimal places is 2.
Events > Value formula has the following entry:
```
@{Item}*@{Quantity}
```
where Item is the control ID of the Single Select control, and Quantity is the control ID of the Integer control.

The Button control has the label OK.

When you run the coach, you see the following screen:

Select an item and enter a quantity, and click OK. This is the result:

Because the Name field in the Single Select control has a numerical value, you can determine the total by the quantity and the item that is selected. The value in the Total field is the unit price (the Control ID of the Single Select control) multiplied by the quantity (the Control ID of the Integer control).

Example: Populating items from a service flow

This example uses a service flow with Ajax access to initialize a list that is used as the selection list.

Note: By default, Ajax access is allowed only to trusted callers. To run the coach within Process Designer, go to the Overview tab in the service flow and change the Ajax access to Allow calls from all callers.

The coach has a Single Select coach view with following configuration properties:

Configuration > Behavior > Label is Grocery List.
Configuration > Behavior > Placeholder is Select Item.
Configuration > Items > Item lookup mode is Items From Service.
Configuration > Items > List items service is Retrieve Items Service.
Note: To create a service flow, click New beside the List items service option.
Configuration > Items > Item selection data has the following settings:
- Value property is name.
- Display property is value.

The service flow is called Retrieve Items Service and has a start event, a server script, and an end event wired together. The server script has the following code to initialize variables:

tw.local.results = new tw.object.listOf.NameValuePair();

tw.local.results[0] = new tw.object.NameValuePair();
tw.local.results[0].name = "Item 0";
tw.local.results[0].value = "Milk";

tw.local.results[1] = new tw.object.NameValuePair();
tw.local.results[1].name = "Item 1";
tw.local.results[1].value = "Bread";

tw.local.results[2] = new tw.object.NameValuePair();
tw.local.results[2].name = "Item 2";
tw.local.results[2].value = "Bananas";

tw.local.results[3] = new tw.object.NameValuePair();
tw.local.results[3].name = "Item 3";
tw.local.results[3].value = "Rice";

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

Image showing a selectable list and a rectangle.

This is the list of selectable items.

The list of items is retrieved from the service flow. The Display property option under Item selection data determines the property that is displayed in the list. If you enter name as the Display property, you will see Item 0, Item 1 etc in the selection list.

When you select an item, the selected item appears in the Item field.

The value in the Item field is determined by the Display property option under Business data mapping, which is also the property that is used as the output of the Single Select control.

Example: Populating items by using a list business object

This example uses a cust[] list object of type Customer to populate a list of first names in the selection list. When the user selects a name, the selection is displayed in a text box. The client-side human service has the private variables cust and output, both of type Customer.

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 cust[] list 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 coach has a Single Select control with the following properties:

General > Label is Name.
General > Binding is output.firstName.
Configuration > Behavior > Placeholder is Select a name.
Configuration > Items > Item lookup mode is Items From Config Option.
Configuration > Items > Item input data is Customer[].
Configuration > Items > Item selection data has the following settings:
- Value property is ID.
- Display property is firstName.
Configuration > Items > Output business data has the following settings:
- Value property is ID.
- Display property is firstName.

The Text control has the following properties:

General > Label is Text.
General > Binding is cust.listSelected.firstName.

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

When you make a selection, the name that you selected is populated in the Text control:

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 Single 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:
${SingleSelect2}.reloadServiceItems(me.getSelectedIndices());
On service items: Activated when the called service returns a list of items. Activated only if Item lookup mode is set to Items From Service.
console.log("SingleSelect1 item service retrieved items successfully");
On service error: Activated when the called service returns an service error. Activated only if Item lookup mode is set to Items From Service
me.clearItems();

Methods

For detailed information on the available methods for the Single Select control, see the Single 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.