5.5.1.1.3. Lookup Screen

Lookup screens are designed to select and return instances or lists of entities. The standard LookupAction in visual components like PickerField and LookupPickerField invokes lookup screens to select related entities.

When a lookup screen is invoked by the openLookup() method, it contains a panel with the buttons for selection. When a user selects an instance or multiple instances, the lookup screen invokes the handler which was passed to it, thus returning results to the calling code. When being invoked by openWindow() method or, for example, from the main menu, the selection panel is not displayed, effectively transforming the lookup screen into a simple screen.

The controller of a lookup screen should be inherited from the AbstractLookup class. The lookupComponent attribute of the screen’s XML must point to a component (for example Table), from which the selected entity instance should be taken as a result of the lookup.

Tip

You can create a lookup screen for an entity in Studio using the Entity browser or Entity combined screen templates.

By default, the LookupAction uses a lookup screen registered in screens.xml with the {entity_name}.lookup or {entity_name}.browse identifier, for example, sales$Customer.lookup. So make sure you have one when using components mentioned above. Studio registers browse screens with {entity_name}.browse identifiers, so they are automatically used as lookup screens.

Customization of the lookup screen look and behavior

  • To change the lookup panel (Select and Cancel buttons) for all lookup screens in the project, create a frame and register it with the lookupWindowActions identifier. The default frame is in /com/haulmont/cuba/gui/lookup-window.actions.xml. Your frame must contain a button linked to the lookupSelectAction action (which is added automatically to the screen when it is opened as a lookup).

  • To replace the lookup panel in a certain screen, just create a button linked to the lookupSelectAction action in the screen. Then the default frame will not be added. For example:

    <layout expand="table">
    <hbox>
        <button id="selectBtn" caption="Select item"
                action="lookupSelectAction"/>
    </hbox>
    <!-- ... -->
</layout>

  • To replace the default select action with a custom one, just add your action in the controller:

    @Override
public void init(Map<String, Object> params) {
    addAction(new SelectAction(this) {
        @Override
        protected Collection getSelectedItems(LookupComponent lookupComponent) {
            Set<MyEntity> selected = new HashSet<>();
            // ...
            return selected;
        }
    });
}

    Use com.haulmont.cuba.gui.components.SelectAction as a base class for your action and override its methods when needed.