entityPicker

entityPicker lets users select an entity instance in a lookup view and run actions for it.

XML Element

entityPicker

Java Class

EntityPicker

Basics

LIVE DEMO

The entityPicker component is commonly used when the field value must represent a reference to an entity. It combines the ability to select a particular entity instance with the ability to perform relevant actions.

Clicking the lookup button opens a dialog with a list view containing entity instances.

Like other views in the application, this view is configurable, allowing multiple attributes to help users easily identify the needed instance. It provides more context than the entityComboBox which only shows instance names.

When the number of instances is large, additional instances are loaded dynamically as you navigate the list.

The following example uses entityPicker to select the department to which a user belongs:

For the example to work correctly, ensure that you define a list view for the Department entity. 
<data>
    <instance id="orderDc"
              class="io.jmix.uisamples.entity.Order">
        <fetchPlan extends="_local">
            <property name="customer" fetchPlan="_local"/>
        </fetchPlan>
    </instance>
</data>
<layout>
    <entityPicker dataContainer="orderDc"
                  property="customer"
                  placeholder="Choose a customer"
                  width="15em">
        <actions>
            <action id="lookup" type="entity_lookup"/>
            <action id="clear" type="entity_clear"/>
        </actions>
    </entityPicker>
</layout>

For more interactive example of entityPicker and its variations, see:

Data-aware entityPicker

Use the dataContainer and property attributes to bind entityPicker to an entity attribute. The data container provides the entity instance, and property identifies the reference attribute to update.

Selecting an Entity

If you simply need a way to select an instance of a specific entity, specify that entity using the metaClass attribute:

<entityPicker metaClass="Department">
    //...
</entityPicker>

Updating a Related Entity Attribute

Selecting an instance is often intended to update an attribute within another instance. In the example above, selecting a Department instance updates the User instance by associating it with the chosen department.

In such cases you will need to bind the component to the data container holding the instance and specify the attribute to be updated using the dataContainer and property attributes respectively:

<entityPicker dataContainer="userDc" property="department">
    //...
</entityPicker>

Actions

You can define custom and predefined actions for entityPicker 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.

Entity Picker with Predefined Actions

When Studio generates entityPicker in the detail view, it also generates two predefined standard actions: entity_lookup and entity_clear. There are also the entity_open and entity_openComposition actions.

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

If you create entityPicker without actions, the XML loader will define only the entity_lookup and entity_clear actions. To add another predefined action, for example, the entity_open, you should specify the actions element as follows:

<entityPicker dataContainer="userDc"
              property="department"
              label="Department" >
    <actions>
        <action id="entityLookup" type="entity_lookup"/>
        <action id="entityClear" type="entity_clear"/>
        <action id="entityOpen" type="entity_open"/>
    </actions>
</entityPicker>

The actions element does not extend but overrides a set of standard actions. You should define the identifiers of all required actions explicitly.

Entity Picker with Custom Actions

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

<entityPicker id="departmentEntityPicker"
              dataContainer="userWithDeptManagerDc"
              property="department">
    <actions>
        <action id="entityLookup" type="entity_lookup"/>
        <action id="knowManager" icon="QUESTION"
                description="Know HR-manager"/>
    </actions>
</entityPicker>

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

@ViewComponent
private EntityPicker<Department> departmentEntityPicker;

@Autowired
private Notifications notifications;

@Subscribe("departmentEntityPicker.knowManager")
public void onKnowManager(ActionPerformedEvent event) {
    Department department = departmentEntityPicker.getValue();
    if (department != null)
        notifications.create(department.getName() + " has "
                + department.getHrManager() + " HR-manager")
                .show();
    else notifications.create("Choose a department").show();
}

You can generate the ActionPerformedEvent handler implementation stub using Studio.

Programmatically Added Actions

Use the addAction() method to set actions programmatically.

  • Adding Standard Action

    For example, if the component is defined in the XML descriptor without the actions nested element, it is sufficient to add missing standard actions:

    @ViewComponent
private EntityPicker<Department> departmentEntityPicker;

@Autowired
private Actions actions;

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

  • Adding Custom Action

    An example of creating a custom action:

    @ViewComponent
private EntityPicker<Department> departmentEntityPicker;

@Subscribe
public void onInit(InitEvent event) {
    departmentEntityPicker.addAction(new BaseAction("showManager")
            .withIcon(VaadinIcon.QUESTION_CIRCLE.create())
            .withHandler(e -> {
                Department department = departmentEntityPicker.getValue();
                if (department != null)
                    notifications.create(department.getName() + " has "
                                    + department.getHrManager() + " HR-manager")
                            .show();
                else notifications.create("Choose a department").show();
            }));
}

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 entityPicker:

Name Description Default

allowCustomValue

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

—

metaClass

You can use entityPicker without binding to the data container, that is, without setting dataContainer and property.

—

The following shared attributes are supported by entityPicker:

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 entityPicker:

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 entityPicker:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - statusChangeHandler

Elements

An entityPicker can include actions, formatter, prefix, suffix, tooltip, and validator as its nested elements.