A combobox lets you select one object or predefined value from a picklist in a ViewModel, and is for users who need to set a single reference without creating a new object.

A combobox is also called a picklist or dropdown list. Use it when the user must choose one item from a manageable list, such as selecting the street for a house or the brand for a car.

Use a combobox for a single link

A combobox is a good fit for a single link: an association end that refers to one object. The combobox displays a collection of candidate objects and writes the selected object to that single link.

For example, a House has one Street. Configure a picklist containing streets, then bind the selected value to House.TheStreet. The user can select a street rather than use a separate Create Street action for each house.

Do not use a combobox for a very large candidate set. A combobox is intended for a list that users can inspect and choose from.

Create the picklist in the ViewModel

In ViewModel Editor, you can create the needed value, picklist, and presentation structure for a single link.

1. Open the ViewModel that contains the object to edit.
2. Locate the single link that the user should set. For example, select TheStreet on a House.
3. Use the singlelink with setter quick action for that link.
4. Review the generated picklist expression. A common starting point is an expression equivalent to Street.allinstances.
5. Change the picklist expression when the user should see a narrower or ordered list. For example, you can order the candidate objects by an attribute using OCL.
6. Set a useful presentation for the candidate class so users can distinguish the items.
7. Re-read the model or refresh the prototype after changing the ViewModel or presentation.

The quick action creates the value that is set, a collection used as the picklist, and the information the UI uses to render the picker. You can move the generated controls in the ViewModel layout as needed.

Make each option understandable

The combobox shows each candidate object's presentation. If no useful default string representation is defined, candidates can appear only as their class name.

For example, if every option displays as Street, define the Street presentation to include identifying data such as the city and street name. A user can then distinguish Gothenburg, Main Street from Stockholm, Main Street.

Configure empty selection

A link may be optional. In that case, configure how the combobox represents a null (no selected object) value in the picklist. The available behaviors are:

Option	Behavior	Example use
None	No null option is displayed.	The user must select a brand.
First	A null option is available as the first option.	Put Choose a color before all color options.
Last	A null option is available as the last option.	Offer No selection after the regular options.
IfEmpty	Null is displayed while nothing is selected, but cannot be selected after the user chooses another option.	Show Choose a street until a street has been selected.

Set the text for the null option with NullRep. For the full behavior and configuration details, see Documentation:How Null is represented in your picklist.

Keep the selected value in the picklist

If a combobox loses its value shortly after it is set, or opens with the wrong value, first verify that the currently selected object is present in the picklist collection.

For example, a House currently refers to Main Street. If the Street picklist filters out Main Street, the combobox cannot represent the current selection. Adjust the picklist expression so it includes the selected Street, even when that object would otherwise be excluded by a filter.

Keep picklist objects stable

A combobox selects objects, not matching text or other value data. A collection can look unchanged while containing newly reconstructed object instances. In that situation, the combobox may no longer recognize its selected object.

Keep the objects used by a picklist stable over time when the list is known and reused. Create the collection for the EcoSpace and reuse it for as long as appropriate. For data that must persist, it can be appropriate to store the candidate objects in the database.

When diagnosing an incorrect selection, check both conditions:

• The selected object is included in the current picklist.
• The picklist contains the same object instances, rather than newly reconstructed equivalents.

Strings and multiple selections

Pick from fixed strings

If the user selects a predefined string rather than an object reference, create a string collection for the combobox. Create Comboboxes with Strings shows how to use the OCL Sequence operator to provide the string options.

For example, bind an OrderColumnName string variable to a combobox whose options are the permitted column names.

Select more than one item

A combobox sets one selected value. If users must select many items, especially when candidates have complex values, use an appropriate multiple-selection widget in PlacingContainers instead of treating a single-value combobox as a multi-select control.

UI-specific implementation

The ViewModel supplies the selected value, picklist, and presentation data. The client UI binds those parts using its own control conventions.

UI scenario	What to use
MVC view	Comboboxes in MVC from model driven ViewModel explains the MVC round trip, including the generated external identity value and the DropDownListFor binding.
MDriven Turnkey view override	Turnkey session 9: View Override shows a select control that binds an object identifier with ng-options.
Generated Turnkey metadata	Getting safe–limited–meta information from a Turnkey app shows the metadata emitted for a combobox, including its picklist and display member.

See also

• Documentation:ViewModel Editor
• Documentation:How Null is represented in your picklist
• HowTos:Create Comboboxes with Strings
• Documentation:Comboboxes in MVC from model driven ViewModel
• Documentation:Turnkey session 9: View Override