SearchPickerField - Платформа CUBA. Руководство по разработке приложений

5.5.2.1.34. SearchPickerField

Компонент SearchPickerField служит для поиска экземпляров сущностей по вводимой пользователем строке. Пользователю достаточно ввести несколько символов и нажать клавишу Enter. Если поиск дал несколько совпадений, найденные значения отображаются в виде выпадающего списка. Если же критерию поиска соответствует только один экземпляр, он сразу становится значением компонента. SearchPickerField позволяет также выполнять действия нажатием на кнопки справа.

См. также SuggestionPickerField.

XML-имя компонента: searchPickerField.

Компонент реализован для блоков Web Client и Desktop Client.

Для работы компонента SearchPickerField необходимо создать collectionDatasource, и задать в нем запрос, содержащий условия поиска. Условие обязательно должно содержать параметр с именем custom$searchString - именно в него компонент передает введенную пользователем подстроку при нажатии Enter. Источник данных с условием поиска должен быть указан в атрибуте optionsDatasource компонента. Например:
```
<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
            where c.name like :(?i)custom$searchString
        </query>
    </collectionDatasource>
</dsContext>
<layout>
    <searchPickerField datasource="carDs" property="colour" optionsDatasource="coloursDs"/>
```
В данном случае компонент будет искать экземпляры сущности Colour по вхождению подстроки в ее атрибут name. Префикс (?i) служит для регистро-независимого поиска (см. Поиск подстроки без учета регистра). Выбранное значение подставится в атрибут colour сущности Car, находящейся в источнике данных carDs.

Атрибут escapeValueForLike со значением true позволяет искать значения, содержащие специальные символы %, \ и _ при помощи like. Чтобы использовать escapeValueForLike = true, необходимо добавить в запрос источника данных escape-значение:
```
select c from ref$Colour c
where c.name like :(?i)custom$searchString or c.description like :(?i)custom$searchString escape '\'
```
Атрибут escapeValueForLike работает со всеми типами базы данных, кроме HSQLDB.

С помощью атрибута minSearchStringLength можно задать минимальное количество символов, которое должен ввести пользователь для поиска значения.

В контроллере экрана для компонента можно реализовать методы, вызываемые в двух случаях:

если количество введенных символов меньше значения атрибута minSearchStringLength.

если поиск введенных пользователем символов не дал результатов.

Пример реализации методов для вывода на экран сообщений:

@Inject
private SearchPickerField colourField;

@Override
public void init(Map<String, Object> params) {
    colourField.setSearchNotifications(new SearchField.SearchNotifications() {
        @Override
        public void notFoundSuggestions(String filterString) {
            showNotification("No colours found for search string: " + filterString,
                             NotificationType.TRAY);
        }

        @Override
        public void needMinSearchStringLength(String filterString, int minSearchStringLength) {
            showNotification("Minimum length of search string is " + minSearchStringLength,
                             NotificationType.TRAY);
        }
    });
}

SearchPickerField реализует интерфейсы LookupField и PickerField, поэтому все описанное для этих интерфейсов в части работы с сущностями верно и для него. Исключением является список действий по умолчанию, добавляемых при определении компонента в XML: для SearchPickerField это действия lookup и open .

Атрибуты searchPickerField: align - caption - captionProperty - contextHelpText - contextHelpTextHtmlEnabled - datasource - description - editable - enable - filterMode - height - icon - id - inputPrompt - metaClass - minSearchStringLength - newOptionAllowed - newOptionHandler - nullName - optionsDatasource - property - required - requiredMessage - stylename - tabIndex - visible - width
Элементы searchPickerField: actions - validator
Предопределённые стили searchPickerField: huge - large
API: addValueChangeListener - setContextHelpIconClickHandler