multiSelectComboBoxPicker

multiSelectComboBoxPicker lets users choose multiple items from a drop-down list or by running picker actions.

XML Element

multiSelectComboBoxPicker

Java Class

JmixMultiSelectComboBoxPicker

Basics

LIVE DEMO

The drop-down list opens when the user clicks the field using a pointing device. Using the Up and Down keys or typing a character when the field is focused also opens the drop-down list.

For multiSelectComboBoxPicker, you can define an arbitrary number of actions, displayed as buttons on the right. It can be done either in the XML descriptor using the actions nested element, or programmatically in the controller using addAction().

<multiSelectComboBoxPicker placeholder="Choose a customers" itemsContainer="customersDc"
                           metaClass="Customer"
                           width="20em">
    <actions>
        <action id="entity_lookup" type="entity_lookup"/>
        <action id="entity_clear" type="entity_clear"/>
    </actions>
</multiSelectComboBoxPicker>

Data-aware multiSelectComboBoxPicker

Data binding refers to linking a visual component to a data container. Changes in the visual component or corresponding data container can trigger updates to one another. See Using Data Components for more details.

Like multiSelectComboBox, multiSelectComboBoxPicker is designed for properties that store multiple values, for example List or Set. See Data Binding for common data structures and use cases.

To create multiSelectComboBoxPicker connected to data, use the dataContainer and property attributes. The itemsContainer attribute is used to provide the list of available items. The following example produces a data-aware multiSelectComboBoxPicker.

<data>
    <instance id="userDc" class="com.company.onboarding.entity.User"> (1)
        <fetchPlan extends="_base"> (2)
            <property name="hobbies" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="userDl"/>
    </instance>
    <collection id="hobbiesDc" class="com.company.onboarding.entity.Hobby"> (3)
        <loader id="hobbiesDl" readOnly="true">
            <query>
                <![CDATA[select e from Hobby e]]>
            </query>
        </loader>
        <fetchPlan extends="_base"/>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/> (4)
</facets>
<layout>
    <multiSelectComboBoxPicker id="hobbiesPicker"
                               dataContainer="userDc"
                               property="hobbies"
                               itemsContainer="hobbiesDc"> (5)
        <actions>
            <action id="entityClear" type="entity_clear"/> (6)
            <action id="entityLookup" type="entity_lookup"/> (7)
        </actions>
    </multiSelectComboBoxPicker>
</layout>
1 Data container to hold the User instance which is currently being edited.
2 Fetch plan extended to retrieve a collection of Hobby instances that will be available for selection.
3 CollectionContainer for the Hobby entity.
4 Data load coordinator to automatically supply the component with instances to select from.
5 multiSelectComboBoxPicker gets hobbiesDc as an items container to show a drop-down list of hobbies.
6 Adding a predefined action to clear the selection.
7 Adding a predefined action to open the lookup view.

The component value contains the selected items. When the component is bound to a collection property, Jmix converts the selected items to the property collection type, for example List or Set.

Using MetaClass

LIVE DEMO

You can use multiSelectComboBoxPicker without directly referencing data, meaning you don’t need to specify dataContainer or property attributes. In this case, use the metaClass attribute to specify the entity type for multiSelectComboBoxPicker. To specify a collection of instances for selection use the itemsContainer attribute.

For example, the component can work with the Hobby entity, which has the metadata class name Hobby.

<multiSelectComboBoxPicker placeholder="Choose a customers" itemsContainer="customersDc"
                           metaClass="Customer"
                           width="20em">
    <actions>
        <action id="entity_lookup" type="entity_lookup"/>
        <action id="entity_clear" type="entity_clear"/>
    </actions>
</multiSelectComboBoxPicker>

Basic Features

The following features, common to comboBox or multiSelectComboBox components, are supported:

Validation

To check values entered into the multiSelectComboBoxPicker component, you can use a validator in a nested validators element.

The following predefined validators are available for multiSelectComboBoxPicker:

XML Element

validators

Predefined validators

custom - notEmpty - notNull - size

Theme Variants

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

align-left

Aligns the field value to the left side.

Aura, Lumo

align-center

Centers the field value.

Aura, Lumo

align-right

Aligns the field value to the right side.

Aura, Lumo

align-start

Aligns the field value to the start side, taking the current text direction into account.

Aura

align-end

Aligns the field value to the end side, taking the current text direction into account.

Aura

helper-above-field

Renders the helper text above the field, below the label.

Aura, Lumo

small

Makes the component smaller.

Aura, Lumo

Attributes

The following attributes are specific to multiSelectComboBoxPicker:

Name Description Default

allowCustomValue

Controls whether users can enter values that are not in the available items.

—

autoExpand

Controls whether selected values expand automatically when the field receives focus.

—

autoOpen

Controls whether the item overlay opens when the field receives focus.

—

clearButtonVisible

Controls whether the field displays a clear button.

false

itemsContainer

Sets the items container.

—

itemsEnum

Sets the items enum.

—

metaClass

Sets the meta class.

—

opened

Controls whether the item overlay is open.

—

overlayClass

Adds CSS class names to the component overlay.

—

pageSize

Sets the page size.

—

selectedItemsOnTop

Sets the selected items on top.

—

The following shared attributes are supported by multiSelectComboBoxPicker:

id - alignSelf - allowedCharPattern - ariaLabel - ariaLabelledBy - autofocus - classNames - colspan - css - dataContainer - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - placeholder - property - readOnly - required - requiredMessage - tabIndex - themeNames - title - visible - width

Handlers

The following handlers are specific to multiSelectComboBoxPicker:

Name Description

CustomValueSetEvent

Fired when the user enters a custom value in the field.

itemLabelGenerator

Provides the text shown for each item.

itemsFetchCallback

Loads items in response to a filter query and paging request.

renderer

Provides the component used to render each item.

validator

Validates the component value.

The following shared handlers are supported by multiSelectComboBoxPicker:

AttachEvent - BlurEvent - ClientValidatedEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - TypedValueChangeEvent

Elements

A multiSelectComboBoxPicker can include actions, fragmentRenderer, itemsQuery, tooltip, and validators as its nested elements.