multiValuePicker

multiValuePicker works with a list of values of any type. It consists of a text field and a set of buttons defined by actions.

XML Element

multiValuePicker

Java Class

JmixMultiValuePicker

Basics

LIVE DEMO

multiValuePicker is ideal for editing lists of values through actions, rather than typing directly in a text field.

Basic multiValuePicker example:

<multiValuePicker id="stringsValuePicker" label="Strings">
    <actions>
        <action id="select" type="multi_value_select">
            <properties>
                <property name="javaClass" value="java.lang.String"/>
            </properties>
        </action>
        <action id="value_clear" type="value_clear"/>
    </actions>
</multiValuePicker>
<multiValuePicker id="integersValuePicker" label="Integers">
    <actions>
        <action id="select" type="multi_value_select">
            <properties>
                <property name="javaClass" value="java.lang.Integer"/>
            </properties>
        </action>
        <action id="value_clear" type="value_clear"/>
    </actions>
</multiValuePicker>

When users click the value selection button, the Select Value view appears. Here, they can add new values to a result list or remove existing ones. To add a value, they can either click the Add button or press Enter.

You can create a custom Select Value view. This view needs to implement the MultiValueSelectView interface and then be set to the action as either viewClass or viewId.

Actions

You can add custom or predefined actions to your multiValuePicker, displayed as buttons on the right side. You can do this in two ways:

  • XML Descriptor: Define your actions within the nested <actions> element in your XML descriptor.

  • Controller: Programmatically add actions to multiValuePicker using the addAction() method in your controller.

To add action in Jmix Studio, select the component in the view descriptor XML or in the Jmix UI structure panel and click on the Add button in the Jmix UI inspector panel.

Predefined Action

The framework provides two predefined actions for multiValuePicker: value_clear and multi_value_select.

The multi_value_select action populates multiValuePicker using a value selection view. This view dynamically generates a component for selecting or creating a value based on the data type provided. The multi_value_select action can handle various data types, including:

  • Java types, such as String, Integer, Long, Double, BigDecimal, date and time types, and UUID

  • enum values

  • entity instances

Use the javaClass property to specify a Java data type. For instance, the previous example uses java.lang.String.

Enumeration Values

LIVE DEMO

Use the enumClass property to specify the enumeration class that represents the data type of the selected value.

<multiValuePicker id="multiValuePicker">
    <actions>
        <action id="select" type="multi_value_select">
            <properties>
                <property name="enumClass" value="io.jmix.uisamples.entity.CustomerGrade"/>
            </properties>
        </action>
        <action id="clear" type="value_clear"/>
    </actions>
</multiValuePicker>

When dealing with enums, a comboBox is generated on the Select Value view, providing a dropdown list of available enum values.

Entity Values

LIVE DEMO

Use the entityName property to set the name of the entity class that represents the data type of the selected value.

<multiValuePicker>
    <actions>
        <action id="select" type="multi_value_select">
            <properties>
                <property name="entityName" value="Customer"/>
            </properties>
        </action>
        <action id="clear" type="value_clear"/>
    </actions>
</multiValuePicker>

The useComboBox property controls whether an entityComboBox should be used in the Select Value view. The default value is false.

Custom Actions

Custom actions for multiValuePicker are similar to custom actions used with valuePicker.

Validation

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

The following predefined validators are available for multiValuePicker:

XML Element

validators

Predefined validators

custom - decimalMax - decimalMin - digits - doubleMax - doubleMin - email - max - min - negative - negativeOrZero - notBlank - notEmpty - notNull - positive - positiveOrZero - regexp - 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 multiValuePicker:

Name Description Default

allowCustomValue

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

—

The following shared attributes are supported by multiValuePicker:

id - alignSelf - ariaLabel - ariaLabelledBy - autofocus - classNames - colspan - css - dataContainer - enabled - 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 multiValuePicker:

Name Description

CustomValueSetEvent

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

formatter

Converts the component value to the text shown in the field.

validator

Validates the component value.

The following shared handlers are supported by multiValuePicker:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - statusChangeHandler

Elements

A multiValuePicker can include actions, formatter, prefix, suffix, tooltip, and validator as its nested elements.