Combobox

Live demo 1
Live demo 2
Live demo 3

Renders a dropdown list.

Node name : combobox

Attributes

Bound

Attribute	Type	Required	Default value	Description
property-name	string	true		UI view property name
item	UI view	false	@DatasourceCurrent	Item to be bound to

Unbound

Attribute	Type	Required	Default value	Description
value	string	true		Input value.
label	string	false		Input label.
disabled	bool	false	false	Value indicating whether the input is disabled
readonly	bool	false	false	Value indicating whether the input is read-only.
required	bool	false	false	Value indicating whether the input is required.
message-text	string	false		Additional message displayed next to the component. Usually a warning or an error message.
message-severity	string (information, warning, error)	false		Severity of the additional message displayed next to the component.
documentation	string	false		Documentation
tab-stop	bool	false	true	Value indicating whether the input can be focused using the Tab key.
value-changed	string	false		Name of the method called when the value has changed. The first parameter is the value and the second is the current item of the data source (DatasourceCurrent) or the iterated item in a repeat component.

Common

Attribute	Type	Required	Default value	Description
label-position	string (top, left, right, hidden)	false	top	Input label position.
message-position	string (bottom, hidden)	false	bottom	Input message position.
focused	bool	false	false	Value indicating whether the component is focused.
enum	string	false		Enumeration name
values	string[], object[]	false if enum is defined, true otherwise		Values list
value-property	string	true if values is object[], false otherwise.		Object property as value
display-property	string	true if values is object[], false otherwise.		Object property as display text
display-mode	string (list, select-button, vertical-radio, horizontal-radio)	false	list	Display mode

Examples

Bound

Enum property

When the UI view property is defined with an enum type, the values are inferred from the property metadata. The enum and values attributes are therefore not required.

<combobox property-name="Status" />

String values

In the following example, we can set the Color property value from a list of ColorNames defined in a field.

<combobox property-name="Color" values="@Fields.ColorNames"/>

Object values

In the following example, we can set the Color property value from a list of Colors data objects defined in a field.

The Color property value will use the Code property of the selected object. It will also use the Caption property of the selected object to display the available entries.

<combobox property-name="Color" values="@Fields.Colors" value-property="Code" display-property="Caption" />

Enum values

In the following example, we can set the Status property value from a list of OrderStatus defined as an enm.

OrderStatus is defined as an enumeration metadata in Neos Studio.

Status is a UI view property with string type.

<combobox property-name="Status" enum="OrderStatus" />

Unbound

String values

In the following example, we can set the OrderStatus field from a list of OrderStatusList defined in a field.

<combobox value="@Fields.OrderStatus" label="@Resources.MyModule.OrderStatusCaption" values="@Fields.OrderStatusList"/>

Object values

In the following example, we can set the CityCode field from a list of Cities data objects defined in a field. The Color property value will use the Code property of the selected object.

It will also use the Caption property of the selected object to display the available entries.

<combobox value="@Fields.CityCode" label="@Resources.MyModule.CityCodeCaption" values="@Fields.Cities" value-property="Code" display-property="Caption" />

Enum values

In the following example, we can set the OrderStatus computed from the OrderStatus enumeration.

<combobox value="@Computeds.OrderStatus" label="@Resources.MyModule.OrderStatusCaption" enum="OrderStatus" />

Customize value and options template

By default, the display-property is displayed. Since version 2.2, it's possible to customize the combobox content:

• The combobox-value-template template is used to customize the content of the current value.
• The combobox-option-template template is used to customize the content of options.

There are two customizable templates, as the options template can contain more information than the value template.

In the following example, each country has a flag, a short caption for the selected value, and a full caption in the dropdown list:

<combobox value="@Fields.CountryCode" label="@Resources.MyModule.CountryCodeCaption" values="@Fields.Countries" value-property="Code" display-property="Caption">
    <combobox-value-template>
        <horizontal-layout wrap="false" layout:width="fill">
            <image name="$Item.Flag" />
            <text>
                $Item.ShortCaption
            </text>
        </horizontal-layout>
    </combobox-value-template>
    <combobox-option-template>
        <horizontal-layout wrap="false" layout:width="fill">
            <image name="$Item.Flag" />
            <text>
                $Item.FullCaption
            </text>
        </horizontal-layout>
    </combobox-option-template>
</combobox>

You can define only the <combobox-option-template> if you want both the selected value and the options to share the same content. In that case, the <combobox-option-template> will be used as the default for rendering the selected value as well.