valuePicker

valuePicker displays a value of any type. It consists of a text field and a set of buttons defined by actions.

XML Element

valuePicker

Java Class

JmixValuePicker

Basics

LIVE DEMO

The component is most often used to select complex values, meaning values where the selection involves some kind of action.

An example of defining valuePicker with a label, and two actions:

XML
<valuePicker id="valuePicker" dataContainer="customerDc" property="name" allowCustomValue="true"
             label="Name" helperText="Generate or type a customer name">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate name"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>
Java
@ViewComponent
protected InstanceContainer<Customer> customerDc;
@Autowired
protected Metadata metadata;

protected List<String> names = List.of("Katherine", "John", "Andy", "Edward", "George",
        "Philipp", "Dora", "James", "Daniel", "Michael", "Claire", "Joan", "Peter", "Martin");
@Subscribe
protected void onInit(InitEvent event) {
    Customer customer = metadata.create(Customer.class);
    customer.setName(getRandomName());
    customerDc.setItem(customer);
}
@Subscribe("valuePicker.generate")
protected void onValuePickerGenerateActionPerformed(ActionPerformedEvent event) {
    customerDc.getItem().setName(getRandomName());
}

@Subscribe("valuePicker")
protected void onValuePickerCustomValueChange(CustomValueSetEvent<JmixValuePicker<String>, String> event) {
    customerDc.getItem().setName(event.getText());
}

protected String getRandomName() {
    return names.get(RandomUtils.secure().randomInt() % names.size());
}

To create valuePicker connected to data, use the dataContainer and property attributes:

<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
    <valuePicker id="valuePicker" dataContainer="customerDc" property="name" allowCustomValue="true"
                 label="Name" helperText="Generate or type a customer name">
        <actions>
            <action id="generate" icon="REFRESH" description="Generate name"/>
            <action id="value_clear" type="value_clear"/>
        </actions>
    </valuePicker>

The customerDc instance container stores a Customer entity. The component is bound to its name property.

Actions

You can define custom and predefined actions for valuePicker displayed as buttons on the right. You can do it either in the XML descriptor using the actions nested element or programmatically in the controller using the addAction() method.

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

Predefined Action

LIVE DEMO

The framework provides only one predefined action - value_clear:

<valuePicker id="valuePicker1" label="Random string">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate value"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>

Use the type and id attributes for declaring predefined action in XML.

Use addAction() to set it programmatically:

@ViewComponent
private JmixValuePicker<String> loginValuePicker;

@Autowired
private Actions actions;

@Subscribe
public void onInit(InitEvent event) {
    loginValuePicker.addAction(actions.create(ValueClearAction.ID));
}

Custom Actions

LIVE DEMO

To define a custom action in XML, use the actions nested element. Specify the id and icon attributes for the action:

<valuePicker id="valuePicker1" label="Random string">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate value"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>

Then implement a custom logic in the screen controller by subscribing to ActionPerformedEvent:

@ViewComponent
protected JmixValuePicker<String> valuePicker1;
@Subscribe("valuePicker1.generate")
protected void onValuePicker1GenerateActionPerformed(ActionPerformedEvent event) {
    generateValue(valuePicker1);
}
protected void generateValue(JmixValuePicker<String> valuePicker) {
    valuePicker.setValue(RandomStringUtils.secure().nextAlphabetic(5, 10));
}

Custom Value Entry

LIVE DEMO

valuePicker allows you to configure it to accept custom values.

When the allowCustomValue attribute is set to true, users can enter custom string values. This triggers CustomValueSetEvent.

valuePicker doesn’t do anything with the custom value string automatically. Use CustomValueSetEvent to determine how the custom value should be handled.

See the example:

@ViewComponent
protected JmixValuePicker<String> valuePicker2;
@Subscribe("valuePicker2")
protected void onValuePicker2CustomValueChange(CustomValueSetEvent<JmixValuePicker<String>, String> event) {
    event.getSource().setValue(event.getText());
}

Formatter

Adds a formatter instance to the component.

In the example below, we will show a formatter usage for the vPicker value picker:

@Install(to = "vPicker", subject = "formatter")
private String vPickerFormatter(String value) {
    return value != null ? "Code: " + value : null;
}

To add formatter programmatically, use the setFormatter() component method.

Validation

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

The following predefined validators are available for valuePicker:

XML Element

validators

elements

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

Name Description Default

allowCustomValue

By default, users can’t manually enter values in the valuePicker field. If you set the allowCustomValue attribute to true, you enable manual input. Keep in mind that the entered value won’t be automatically set in the data model. To handle user input, use CustomValueSetEvent. See Custom Value Entry.

false

The following shared attributes are supported by valuePicker:

id - alignSelf - 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 valuePicker:

Name Description

CustomValueSetEvent

io.jmix.flowui.kit.component.valuepicker.CustomValueSetEvent is fired when the user enters a non-empty value. To enable input custom values, set the allowCustomValue attribute to true. See Custom Value Entry.

formatter

Adds a formatter instance to the component. See Formatter.

validator

Validates the component value.

The following shared handlers are supported by valuePicker:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - statusChangeHandler

Elements

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