SearchPickerField - CUBA Platform. Developer’s Manual

3.5.2.1.39. SearchPickerField

The SearchPickerField component is used to search for entity instances according to the entered string. A user should enter a few characters and press Enter. If several matches have been found, all of them will be displayed in a drop-down list. If only one instance matches the search query, it immediately becomes a component value. SearchPickerField also enables performing actions by clicking on buttons on the right.

SearchPickerField works only in screens based on legacy API. The similar functionality for the current API is provided by the SuggestionPickerField component.

XML name of the component: searchPickerField.

To use SearchPickerField component, you need to create collectionDatasource and specify a query, which contains corresponding search conditions. Condition must contain a parameter named custom$searchString. This parameter will be populated with a substring entered by the user. A data source with a search condition should be defined in the optionsDatasource attribute of the component. For example:
```
<dsContext>
    <datasource id="carDs" class="com.company.sample.entity.Car" view="_local"/>
    <collectionDatasource id="colorsDs" class="com.company.sample.entity.Color" view="_local">
        <query>
            select c from sample$Color c
            where c.name like :(?i)custom$searchString
        </query>
    </collectionDatasource>
</dsContext>
<layout>
    <searchPickerField datasource="carDs" property="color" optionsDatasource="colorsDs"/>
</layout>
```
In this case, the component will look for instances of Colour entity according to the occurrence of the substring in its name attribute. The (?i) prefix is used for case-insensitive search (see Case-Insensitive Search for a Substring). The selected value will be set in the colour attribute of the Car entity located in the carDs datasource.

The escapeValueForLike attribute set to true enables searching for the values that contain special symbols %, \, and _ using like-clauses. In order to use escapeValueForLike = true, modify the query of the collection data source adding the escape value to it:
```
select c from ref$Colour c
where c.name like :(?i)custom$searchString or c.description like :(?i)custom$searchString escape '\'
```
The escapeValueForLike attribute works for all databases except HSQLDB.

Using the minSearchStringLength attribute the minimum number of characters, which the user should enter to search for values, can be defined.

In the screen controller, two component methods can be implemented that will be invoked:

If the number of entered characters is less than the value of minSearchStringLength attribute.
If the search of characters entered by the user has returned no results.

Below is an example of implementing methods to display messages to the user:

@Inject
private Notifications notifications;
@Inject
private SearchPickerField colorField;

@Subscribe
protected void onInit(InitEvent event) {
    colorField.setSearchNotifications(new SearchField.SearchNotifications() {
        @Override
        public void notFoundSuggestions(String filterString) {
            notifications.create()
                    .withCaption("No colors found for search string: " + filterString)
                    .withType(Notifications.NotificationType.TRAY)
                    .show();
        }

        @Override
        public void needMinSearchStringLength(String filterString, int minSearchStringLength) {
            notifications.create()
                    .withCaption("Minimum length of search string is " + minSearchStringLength)
                    .withType(Notifications.NotificationType.TRAY)
                    .show();
        }
    });
}

SearchPickerField implements LookupField and PickerField interfaces. Thus, it inherits the same functionality except the default list of actions added when defining the component in XML: for SearchPickerField these are lookup and open actions.

Attributes of searchPickerField: align - caption - captionAsHtml - captionProperty - contextHelpText - contextHelpTextHtmlEnabled - css - datasource - description - descriptionAsHtml - editable - enable - escapeValueForLike - box.expandRatio - filterMode - height - icon - id - inputPrompt - metaClass - minSearchStringLength - newOptionAllowed - newOptionHandler - nullName - optionsDatasource - property - required - requiredMessage - stylename - tabIndex - visible - width
Elements of searchPickerField: actions - validator
Predefined styles of searchPickerField: huge - large
API: addValueChangeListener - setContextHelpIconClickHandler - setOptionCaptionProvider