4.5.2.1.14. LookupField

This is a component to select a value from drop-down list. Drop-down list provides the filtering of values as the user inputs some text, and the pagination of available values.

XML name of the component: lookupField.

The LookupField component is implemented for Web Client and Desktop Client.

  • The simplest case of using LookupField is to select an enumeration value for an entity attribute. For example, a Role entity has a type attribute of the RoleType type, which is an enumeration. Then you can use LookupField to edit this attribute as follows: 

    <dsContext>
    <datasource id="roleDs" class="com.haulmont.cuba.security.entity.Role" view="_local"/>
</dsContext>
<layout>
    <lookupField datasource="roleDs" property="type"/>

    In the example above, the screen defines roleDs data source for the Role entity. In the lookupField component, you should specify a link to a data source in the datasource attribute, and a name of an entity attribute, which value should be displayed in the property attribute. In this case, the attribute is an enumeration and the drop-down list will display localized names of all enumeration values.

  • Similarly, LookupField can be used to select an instance of a related entity. optionsDatasource attribute is used to create a list of options: 

    <dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    <collectionDatasource id="coloursDs" class="com.company.sample.entity.Colour" view="_local">
        <query>select c from sample$Colour c</query>
    </collectionDatasource>
</dsContext>
<layout>
    <lookupField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>

    In this case, the component will display instance names of the Colour entity located in the colorsDs data source, and the selected value will be put into the colour attribute of the Car entity, which is located in the carDs data source.

    captionProperty attribute defines which entity attribute can be used instead of an instance name for string option names.

  • The list of component options can be specified arbitrarily using setOptionsList() and setOptionsMap(), or using an XML optionsDatasource attribute.

    • setOptionsList() allows you to programmatically specify a list of component options. To do this, declare a component in the XML descriptor: 

      <lookupField id="numberOfSeatsField" datasource="modelDs" property="numberOfSeats"/>

      Then inject the component into the controller and specify a list of options in the init() method: 

      @Inject
protected LookupField numberOfSeatsField;

@Override
public void init(Map<String, Object> params) {
    List<Integer> list = new ArrayList<>();
    list.add(2);
    list.add(4);
    list.add(5);
    list.add(7);
    numberOfSeatsField.setOptionsList(list);
}

      In the dropdown list of the component values 2, 4, 5 and 7 will be displayed. Selected number will be put into the numberOfSeats attribute of an entity located in the modelDs data source.

    • setOptionsMap() allows you to specify string names and option values separately. For example, in the numberOfSeatsField component in the XML descriptor, specify an option map in init(): 

      @Inject
protected LookupField numberOfSeatsField;

@Override
public void init(Map<String, Object> params) {
    Map<String, Object> map = new LinkedHashMap<>();
    map.put("two", 2);
    map.put("four", 4);
    map.put("five", 5);
    map.put("seven", 7);
    numberOfSeatsField.setOptionsMap(map);
}

      In the drop down list of the component, two, four, five, seven strings will be displayed. However, the value of the component will be a number that corresponds to the selected row. It will be put into the numberOfSeats attribute of an entity located in the modelDs data source.

  • Using the filterMode attribute, option filtering type can be defined for the user input:

    • NO − no filtering.

    • STARTS_WITH − by the beginning of a phrase.

    • CONTAINS − by any occurrence (is used by default).

  • If the LookupField component has no required attribute to set up and if the related entity attribute is not declared as required, the list of component options has an empty row. If this row is selected, the component returns null. The nullName attribute allows you to specify a row to be displayed in this case instead of an empty one. Below is an example of use: 

    <lookupField datasource="carDs" property="colour" optionsDatasource="coloursDs" nullName="(none)"/>

    In this case, instead of an empty row, (none) will be displayed. If this row is selected, null will be put into a related entity attribute.

    If you specify a list of options programmatically using setOptionsList() , you can pass one of the options into setNullOption() method. Then, if the user selects it, the component value will be null.

  • The LookupField component is able to handle user input if there is no suitable option in the list. In this case, setNewOptionAllowed() and setNewOptionHandler() are used. For example: 

    @Inject
protected LookupField colourField;

@Inject
protected CollectionDatasource<Colour, UUID> coloursDs;

@Override
public void init(Map<String, Object> params) {
    colourField.setNewOptionAllowed(true);
    colourField.setNewOptionHandler(new LookupField.NewOptionHandler() {
        @Override
        public void addNewOption(String caption) {
            Colour colour = new Colour();
            colour.setName(caption);
            coloursDs.addItem(colour);
            colourField.setValue(colour);
        }
    });
}

    The NewOptionHandler handler is invoked if the user enters a value that does not coincide with any option and presses Enter. In this case, a new Colour entity instance is created in the handler, its name attribute is set to the value entered by the user, this instance is added to an option data source and selected in the component.

    Instead of implementing the LookupField.NewOptionHandlerinterface for processing user input, the controller method name can be specified in the newOptionHandler XML-attribute. This method should have two parameters, one of LookupField, and the other of Stringtype. They will be set to the component instance and the value entered by the user, accordingly.

lookupField attributes:

align | caption | captionProperty | datasource | description | editable | enable | filterMode | height | id | inputPrompt | newOptionHandler | nullName | optionsDatasource | property | required | requiredMessage | stylename | visible | width

lookupField elements:

validator

Prev  Up  Next
  Home