genericFilter

ДЕМО

Компонент genericFilter - это универсальный инструмент для динамической фильтрации данных.

Компонент позволяет быстро фильтровать данные с помощью набора временных условий, а также создавать конфигурации для повторного использования.

  • XML-элемент: genericFilter

  • Java-класс: GenericFilter

Основы

Компонент genericFilter добавляется по умолчанию в некоторые стандартные экраны, такие как экран списка сущности. Типичный фильтр показан ниже:

generic filter anatomy

  1. Кнопка Refresh с выпадающим меню.

  2. Селектор оператора сравнения.

  3. Кнопка Filter Settings.

  4. Список сохраненных фильтров и конфигураций.

  5. Поле значения условия.

  6. Ссылка Add search condition.

Для работы компонент genericFilter должен быть подключен к загрузчику данных автономного CollectionContainer или KeyValueCollectionContainer. Он генерирует объект Condition, который устанавливается в загрузчик и впоследствии обрабатывается хранилищем данных. Для сущности JPA хранилище данных преобразует полученный запрос JPQL, так что фильтрация выполняется на уровне базы данных, и затем только результат загружается из базы данных в память приложения.

В следующем примере демонстрируется базовый genericFilter и некоторые связанные компоненты:

<data>
    <collection id="customerDc" class="com.company.onboarding.entity.Customer">  (1)
        <fetchPlan extends="_base">
        </fetchPlan>
        <loader id="customerDl">
            <query>
                <![CDATA[select c from Customer c]]> (2)
            </query>
        </loader>
    </collection>
</data>
<layout>
    <genericFilter id="genericFilter" dataLoader="customerDl"> (3)
        <properties include=".*"/>
    </genericFilter>
    <dataGrid id="customersTable"
              width="100%"
              dataContainer="customerDc"> (4)
        <columns>
            <column property="level"/>
            <column property="age"/>
            <column property="hobby"/>
            <column property="firstName"/>
            <column property="lastName"/>
            <column property="rewardPoints"/>
        </columns>
    </dataGrid>
</layout>
1 Контейнер данных содержит коллекцию экземпляров сущности Customer.
2 Компонент загрузчика объявляет JPQL-запрос для загрузки всех экземпляров Customer.
3 Компонент genericFilter связан с загрузчиком через его атрибут dataLoader.
4 dataGrid отображает данные из контейнера данных. Список записей будет изменяться по мере фильтрации.

Пример быстрого фильтра

По умолчанию компонент находится в режиме быстрого фильтра. Это означает, что пользователь может добавить временный набор условий, который остается в силе только на время текущей сессии страницы. После закрытия страницы условия исчезнут.

Предположим, у нас есть сущность Customer, и мы хотим:

  • Создать быстрый фильтр с несколькими условиями в экране списка клиентов.

  • Сохранить этот фильтр для использования в будущем.

Создание быстрого фильтра

  • Нажмите Add search condition.

  • Выберите свойства, по которым нужно фильтровать. Например: Age и Hobby.

  • Выберите оператор и введите значение для каждого свойства.

generic filter quick

Сохранение конфигурации

  • Нажмите generic filter settings button→ Save with values.

  • Введите название конфигурации и нажмите OK, чтобы сохранить:

    generic filter save

Теперь эту конфигурацию можно выбрать в выпадающем меню.

generic filter refresh

Чтобы сбросить все примененные в данный момент условия, выберите пункт меню <Reset filter> вверху.

Добавление условий

Нажмите ссылку Add search condition [6], чтобы открыть диалоговое окно Add condition:

generic filter add condition dialog

Возможные типы условий следующие:

  • Properties - атрибуты этой и связанных сущностей, которые можно использовать в качестве свойств фильтра. Они отображаются в соответствии с правилами, указанными в элементе properties, и могут включать как постоянные, так и динамические атрибуты.

  • Predefined conditions - условия, заданные разработчиком во время разработки в элементе conditions.

  • Configurations - существующие конфигурации фильтра. Они могут быть созданы либо разработчиком во время разработки, либо пользователем во время выполнения.

После добавления условие появляется на панели условий. Если условие больше не нужно, его можно удалить, нажав на значок generic filter remove рядом с ним.

Создание условий

Если подходящего условия еще нет, можно перейти к его созданию из того же диалогового окна. Действия выпадающего списка кнопки Create соответствуют зарегистрированным компонентам фильтра.

generic filter create button

По умолчанию доступны три таких компонента: propertyFilter, jpqlFilter и groupFilter.

При нажатии на действие открывается соответствующий редактор условий:

Расширенный полнотекстовый поиск доступен как часть дополнения Search.

Условия свойства

Редактор условий Property condition позволяет пользователям установить атрибут сущности в качестве параметра фильтра и выполнять фильтрацию по нему. Используйте Add search condition → + Create → Create Property condition, чтобы открыть редактор.

generic filter property condition editor

Редактор имеет следующие элементы управления и поля:

  • Property - принимает атрибут сущности.

  • Operation - устанавливает оператор сравнения. Список отображает только те операторы, которые совместимы с текущим свойством.

  • Parameter name - устанавливает имя соответствующего параметра запроса. Используйте это имя для установки зависимостей между условиями одной и той же конфигурации. Если не задано, имя параметра генерируется случайным образом.

  • Label - задает пользовательскую надпись для этого условия, которая отображается на панели и в редакторах.

  • Default value - задает значение по умолчанию.

  • Operation editable - разрешает выбор типа операции сравнения.

  • Operation text visible - определяет, отображается ли название операции.

  • Visible - определяет, отображается ли это условие на панели условий.

Условия JPQL

Редактор условий JPQL condition позволяет пользователям создавать условия на основе выражений JPQL. Используйте Add search condition → + Create → Create JPQL condition, чтобы открыть редактор.

generic filter jpql condition editor

Ниже представлены описания полей:

  • Parameter type - принимает класс Java, представляющий желаемый тип параметра. Вы также можете выбрать опцию No parameter, чтобы создать условие без параметра.

    generic filter jpql condition editor no parameter

    Условие без параметра действует подобно тегу - оно отфильтровывает данные на основе предопределенного, постоянного критерия.

  • Label - устанавливает надпись для этого условия, которая отображается на панели и в редакторах.

  • Parameter name - устанавливает имя соответствующего параметра запроса. Используйте это имя для установки зависимостей между условиями одной и той же конфигурации. Если не задано, то имя параметра генерируется случайным образом.

  • Default value - устанавливает значение по умолчанию для этого условия. Это поле будет представлено компонентом, совместимым с текущим значением в поле Parameter type.

  • Has IN expression - определяет, может ли условие обработать коллекцию и поместить ее внутрь предложения IN.

  • Visible - определяет, отображается ли это условие на панели фильтра.

  • Join - указывает необязательное предложение join, которое будет включено в предложение from загрузчика данных. Это можно использовать для создания условий на основе атрибута связанной коллекции.

    При написании этого предложения:

    • Начинайте с ключевых слов join или left join.

    • Используйте плейсхолдер {E} вместо псевдонима сущности.

      Например:

      join {E}.city c

  • Where - указывает предложение where, которое будет добавлено к запросу select загрузчика данных.

    При написании этого предложения:

    • Используйте плейсхолдер {E} вместо псевдонима сущности.

    • Установите ? в качестве значения параметра, чтобы указать, что оно должно быть передано пользователем. В условии может быть только один такой параметр. Кроме того, может быть любое количество параметров атрибутов сессии и пользователя.

      Например:

      {E}.code = ? and {E}.area = :session_area

Условия группы

Редактор условий Group condition позволяет пользователям объединять условия в логическую группу. Используйте Add search condition → + Create → Create Property condition, чтобы открыть редактор.

generic filter group condition editor

Этот редактор имеет две области - одну для настройки основных свойств группы, а другую для добавления и отображения условий, входящих в группу в данный момент. Описание полей в каждой области приведено ниже.

Условие группы

  • Operation - логический оператор, используемый для объединения условий в группе. Группа имеет два логических оператора: AND или OR.

  • Label - задает надпись для этого условия, которая отображается на панели условий и в редакторах. Если не задано, вместо этого отображается имя операции (AND или OR).

  • Operation text visible - определяет, отображается ли название операции.

  • Visible - определяет, отображается ли эта группа на панели фильтра.

Условия

Условия группы отображаются в виде дерева. Используйте следующие действия для управления ими.

  • Add - открывает диалоговое окно Add condition, позволяющее выбрать необходимые условия.

  • Edit - открывает соответствующий редактор для условия, выбранного в дереве.

  • Remove - удаляет все условия, которые в данный момент выбраны в дереве.

  • generic filter move up/generic filter move down - кнопки для изменения порядка отображения условий группы.

Конфигурация

Конфигурация - это набор условий, сохраненный для последующего использования. Он может включать условия любого типа, а также другие конфигурации.

Конфигурации могут быть созданы либо разработчиком во время разработки, либо пользователем во время выполнения.

Конфигурация времени разработки

Конфигурация времени разработки - это набор вложенных элементов genericFilter в XML-дескрипторе экрана.

Следующий пример объявляет genericFilter с двумя конфигурациями времени разработки:

<genericFilter id="filterWithConfigs" dataLoader="customerDl">
    <properties include=".*"/>
    <configurations>
        <configuration id="configuration_age_hobby" operation="AND"
                       name="Age AND Hobby Configuration"> (1)
            <propertyFilter property="age" operation="GREATER"/>
            <propertyFilter property="hobby" operation="CONTAINS"/>
        </configuration>
        <configuration id="configuration_level_rewards_points" operation="OR"
                       name="Level OR Reward Points Configuration" default="true"> (2)
            <propertyFilter property="level" operation="EQUAL"/>
            <propertyFilter property="rewardPoints" operation="LESS_OR_EQUAL"/>
        </configuration>
    </configurations>
</genericFilter>
1 Убедитесь, что каждая конфигурация указывает атрибут id, и его значение является уникальным в пределах этого genericFilter. Если атрибут name не указан, id рассматривается как ключ в пакете сообщений.
2 Конфигурацию по умолчанию можно установить с помощью атрибута default.
Чтобы добавить конфигурацию времени разработки в Jmix Studio, выберите компонент genericFilter в дескрипторе экрана или на панели структуры Jmix UI, затем используйте пункт меню Add → Configurations → Design-time configuration на панели Component Inspector.

Конфигурация времени разработки не позволяет пользователям выполнять какие-либо настройки во время выполнения и не может быть удалена пользователем. Однако пользователи могут создать идентичную конфигурацию времени выполнения на основе конфигурации времени разработки и изменить ее параметры. Это можно сделать с помощью действия меню generic filter settings button → Copy.

Во время работы приложения конфигурации времени разработки отображаются в выпадающем меню [4] среди других конфигураций.

generic filter design time items

Конфигурация времени выполнения

Конфигурации могут быть созданы во время выполнения в редакторе конфигураций Configuration. Чтобы открыть редактор, используйте пункт меню generic filter settings button → Edit.

Для создания, редактирования или удаления конфигурации времени выполнения пользователю необходимо предоставить разрешение безопасности ui.genericfilter.modifyConfiguration.
generic filter run time configuration

Чтобы создать конфигурацию времени выполнения:

  • Укажите название конфигурации. Это название отображается в выпадающем меню [4] и в редакторах конфигураций.

  • Установите флажок Available for all users, чтобы разрешить любому пользователю использовать эту конфигурацию. Этот флажок доступен только пользователям, которым предоставлено разрешение ui.filter.modifyGlobalConfiguration.

  • Установите флажок Default for all users, чтобы автоматически применять эту конфигурацию при открытии экрана пользователями. Этот флажок становится активным, если выбран флажок Available for all users.

  • Настройте операцию группы и добавьте условия в группу. Описание полей смотрите в разделе Условия группы.

Разрешения

Для расширенного управления фильтрами требуются следующие разрешения:

  • Чтобы создавать/редактировать/удалять конфигурации genericFilter, пользователю должно быть предоставлено разрешение безопасности ui.genericfilter.modifyConfiguration.

  • Чтобы создавать/редактировать/удалять глобальные конфигурации (доступные для всех пользователей), пользователям должно быть предоставлено разрешение безопасности ui.genericfilter.modifyGlobalConfiguration.

  • Чтобы создавать/изменять условия JPQL во время выполнения, пользователям должно быть предоставлено разрешение безопасности ui.genericfilter.modifyJpqlCondition.

Свойства приложения

Следующие свойства приложения влияют на поведение фильтра:

Создание фильтра программно

В этом разделе приведен пример конфигурации genericFilter, созданной программно.

@Autowired
private UiComponents uiComponents;

@ViewComponent
private VerticalLayout programmaticFilterBox;

@ViewComponent
private CollectionLoader<Customer> customerDl;

@Autowired
private SingleFilterSupport singleFilterSupport;

@Subscribe
public void onInit(final InitEvent event) {
    GenericFilter genericFilter = uiComponents.create(GenericFilter.class); (1)
    genericFilter.setId("programmaticFilter");
    genericFilter.setDataLoader(customerDl);
    genericFilter.loadConfigurationsAndApplyDefault();

    DesignTimeConfiguration javaDefaultConfiguration =
            genericFilter.addConfiguration("javaDefaultConfiguration",
                    "Default configuration"); (2)

    PropertyFilter<Integer> agePropertyFilter =
            uiComponents.create(PropertyFilter.class); (3)

    agePropertyFilter.setConditionModificationDelegated(true);
    agePropertyFilter.setDataLoader(customerDl);
    agePropertyFilter.setProperty("age");
    agePropertyFilter.setOperation(PropertyFilter.Operation.LESS_OR_EQUAL);
    agePropertyFilter.setOperationEditable(true);
    agePropertyFilter.setParameterName(PropertyConditionUtils
            .generateParameterName(agePropertyFilter.getProperty()));
    agePropertyFilter.setValueComponent(singleFilterSupport.generateValueComponent(
            customerDl.getContainer().getEntityMetaClass(),
            agePropertyFilter.getProperty(),
            agePropertyFilter.getOperation())); (4)

    javaDefaultConfiguration.getRootLogicalFilterComponent().add(agePropertyFilter); (5)

    programmaticFilterBox.add(genericFilter); (6)

    genericFilter.setCurrentConfiguration(javaDefaultConfiguration); (7)
}
1 Создает genericFilter, используя фабрику uiComponents.
2 Добавляет конфигурацию времени разработки. Метод принимает два параметра: id конфигурации и название конфигурации.
3 Создает экземпляр PropertyFilter и устанавливает его свойства.
4 Генерирует компонент для этого фильтра на основе metaClass, property и operation.
5 Добавляет фильтр в конфигурацию. LogicalFilterComponent является корневым элементом конфигурации.
6 Помещает genericFilter в экран внутри компоновщика vbox. Этот компоновщик объявлен в дескрипторе экрана и внедрен в контроллер.
7 Устанавливает текущую конфигурацию.

Атрибуты

id - alignSelf - applyShortcut - autoApply - classNames - colspan - css - dataLoader - enabled - height - maxHeight - maxWidth - minHeight - minWidth - opened - propertyHierarchyDepth - summaryText - themeNames - visible - width

applyShortcut

Определяет комбинацию клавиш, которую можно использовать для применения условия фильтрации. Эта комбинация клавиш актуальна только в том случае, если условия фильтрации не настроены для автоматического применения.

Значение по умолчанию определяется свойством jmix.ui.component.filter-apply-shortcut.

autoApply

Определяет, применяется ли фильтр автоматически.

  • Если установлено значение true, фильтр применяется немедленно после обновления условия фильтрации или в любой момент, когда он теряет фокус.

  • Если установлено значение false, фильтр будет применен только после нажатия кнопки [1] или использования applyShortcut. Обратите внимание, что установка значения false обновляет текст кнопки на Apply.

Значение по умолчанию определяется свойством jmix.ui.component.filter-auto-apply.

dataLoader

Устанавливает загрузчик данных, который будет загружать данные на основе условия фильтрации.

opened

Определяет, открыта ли панель условий.

propertyHierarchyDepth

Устанавливает количество уровней вложенности, на которых применяется фильтр. Можно указать любое разумное, ненулевое количество уровней. По умолчанию - 2.

generic filter hierarchy depth

  • propertyHierarchyDepth = "1" – фильтрует только непосредственные свойства сущности.

  • propertyHierarchyDepth = "2" – фильтрует свойства сущности, а также свойства всех дочерних сущностей.

  • propertyHierarchyDepth = "3" – фильтрует непосредственные свойства сущности и до третьего уровня вложенности свойств.

Это значение можно указать глобально для всех компонентов фильтра, установив свойство jmix.ui.component.filter-properties-hierarchy-depth.

summaryText

Определяет краткое описание, которое будет отображаться над панелью управления фильтром. Значение по умолчанию - Filter.

Обработчики

AttachEvent - ConfigurationChangeEvent - ConfigurationRefreshEvent - DetachEvent - OpenedChangeEvent - propertyFiltersPredicate

ConfigurationChangeEvent

ConfigurationChangeEvent отправляется при каждом переключении одной конфигурации фильтра на другую. Это включает в себя переключение на конфигурацию, когда никакая конфигурация не установлена, или сброс конфигурации.

ConfigurationRefreshEvent

ConfigurationRefreshEvent отправляется каждый раз, когда редактируется конфигурация фильтра.

OpenedChangeEvent

OpenedChangeEvent отправляется каждый раз, когда изменяется атрибут opened компонента.

propertyFiltersPredicate

Этот предикат позволяет программно включать или исключать атрибуты, доступные для выбора пользователем.

Например, чтобы исключить hobby из выбора пользователя, используйте следующий код:

@Install(to = "genericFilter", subject = "propertyFiltersPredicate")
private boolean genericFilterPropertyFiltersPredicate(final MetaPropertyPath metaPropertyPath) {
    return !metaPropertyPath.getMetaProperty().getName().equals("hobby");
}

Элементы

actions - conditions - configurations - properties - responsiveSteps - tooltip

actions

Определяет список действий для управления фильтром. Фреймворк предоставляет следующие действия по умолчанию, доступные в меню настроек generic filter settings button Filter Settings:

  • Save - сохраняет изменения в текущей конфигурации. Реализовано с помощью FilterSaveAction (type="genericFilter_save" в XML).

  • Save with values - сохраняет изменения в текущей конфигурации вместе со значениями в полях условий [5] в качестве значений по умолчанию.

  • Save as - сохраняет текущую конфигурацию под другим именем. Реализовано с помощью FilterSaveAsAction (type="genericFilter_saveAs" в XML).

  • Edit - открывает редактор для текущей конфигурации времени выполнения. Отключено для конфигураций времени разработки. Реализовано с помощью FilterEditAction (type="genericFilter_edit" в XML).

  • Remove - удаляет текущую конфигурацию времени выполнения. Отключено для конфигураций времени разработки. Реализовано с помощью FilterRemoveAction (type="genericFilter_remove" в XML).

  • Copy - создает копию времени выполнения для текущей конфигурации. Реализовано с помощью FilterCopyAction (type="genericFilter_copy" в XML).

  • Clear values - очищает значения в полях условий [5]. Реализовано с помощью FilterClearValuesAction (type="genericFilter_clearValues" в XML).

  • Add - добавляет условие в текущую конфигурацию. Реализовано с помощью FilterAddConditionAction (type="genericFilter_addCondition" в XML).

  • Reset - сбрасывает. Реализовано с помощью FilterResetAction (type="genericFilter_reset" в XML).

Разработчики могут переопределить список действий в меню настроек generic filter settings button:

<genericFilter id="filterWithActions" dataLoader="customerDl">
    <properties include=".*"/>
    <actions>
        <action id="addCondition" type="genericFilter_addCondition"/>
        <action id="clearValues" type="genericFilter_reset"/>
    </actions>
</genericFilter>

В приведенном выше примере создается фильтр с двумя действиями меню:

generic filter settings menu actions

conditions

Содержит объявление предопределенных условий.

Смотрите следующий пример для иллюстрации:

<genericFilter id="filterWithCondition" dataLoader="customerDl">
    <properties include=".*"/>
    <conditions>
        <propertyFilter property="hobby" enabled="true" operation="STARTS_WITH"/>
    </conditions>
</genericFilter>

configurations

Содержит объявление конфигураций времени разработки.

properties

Определяет, какие атрибуты сущности можно добавлять в условие. Этот элемент имеет следующие атрибуты:

  • include - указывает регулярное выражение. Атрибуты сущности, соответствующие этому выражению, включаются.

  • exclude - указывает регулярное выражение. Атрибуты сущности, соответствующие этому выражению, исключаются.

  • excludeProperties - указывает список имен свойств или путей к свойствам, разделенных запятыми, которые следует исключить. Например: customer.name.

  • excludeRecursively - определяет, должен ли атрибут в excludeProperties быть рекурсивно исключен для всего графа объектов. То есть, если значение true, любые дочерние атрибуты исключенного атрибута также исключаются.

Смотрите следующий пример для иллюстрации:

<genericFilter id="filterWithProperties" dataLoader="customerDl">
    <properties include=".*"
                exclude="(hobby)|(age)"
                excludeProperties="id"
                excludeRecursively="true"/>
</genericFilter>

Вы можете включать и исключать свойства коллекции (@OneToMany, @ManyToMany).

Вы можете включать и исключать динамические атрибуты в качестве условия фильтрации. Это не требует фасета dynamicAttributes в этом экране.

Укажите код атрибута с префиксом "+":

<genericFilter id="genericFilter"
               dataLoader="carsDl">
    <properties include=".*"
                excludeProperties="+passengerNumberOfSeats"/>/>
</genericFilter>

Обратите внимание, что если такой атрибут является сущностью, а не простым значением, вы не можете использовать атрибуты этой сущности как часть условия фильтрации.

Следующие атрибуты сущности игнорируются:

  • Недоступные из-за разрешений безопасности

  • Неперсистентные атрибуты

  • Атрибуты, аннотированные @SystemLevel

  • Атрибуты типа byte[]

responsiveSteps

Определяет количество столбцов для отображения условий поиска в зависимости от доступного места. По умолчанию условия поиска располагаются в два столбца и перестраиваются в один столбец, когда ширина макета становится меньше.

Следующий фильтр переопределяет поведение по умолчанию, чтобы настроить макет на один, два или три столбца с надписями, расположенными сверху:

generic filter responsive steps 
<layout>
    <genericFilter dataLoader="customerDl">
        <responsiveSteps>
            <responsiveStep minWidth="0" columns="1"/>
            <responsiveStep minWidth="30em" columns="2"/>
            <responsiveStep minWidth="50em" columns="3" labelsPosition="TOP"/>
        </responsiveSteps>
    </genericFilter>
</layout>