PropertyFilter

Компонент PropertyFilter используется для отображения одного условия фильтрации. Он связан со свойством entity и может автоматически отображать нужную компоновку для установки значения условия.

Данный компонент может использоваться как внутри компонента Filter, так и отдельно от него.

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

Основы

В общем случае PropertyFilter состоит из надписей с именем свойства сущности, с операцией (=, contains, in, >, и т.д.) и поля для редактирования значения условия.

Пример объявления propertyFilter приведен ниже.

<data>
    <collection id="customersDc" class="ui.ex1.entity.Customer">
        <fetchPlan extends="_base">
            <property name="city" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="customersDl">
            <query>
                <![CDATA[select e from uiex1_Customer e]]>
            </query>
        </loader>
    </collection>
</data>
<layout spacing="true" expand="customersTable">
    <propertyFilter property="age"
                    operation="GREATER_OR_EQUAL"
                    dataLoader="customersDl">
    </propertyFilter>
</layout>

dataLoader, property, и operation являются обязательными атрибутами.

dataLoader задает загрузчик данных, связанный с текущим PropertyFilter.

property содержит имя атрибута сущности или путь к атрибуту (например, name, order, order.date).

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

<propertyFilter property="+PassengerNumberofseats"
                operation="GREATER_OR_EQUAL"
                dataLoader="carsDl"/>

Необязательно иметь на экране фасет dynamicAttributes.

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

Можно использовать несколько компонентов PropertyFilter в экране. Имеющие значения компоненты применяются к загрузчикам данных.

Операции

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

EQUAL подходит для строковых, числовых, ссылочных атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута равно значению условия в фильтре.
NOT_EQUAL подходит для строковых, числовых, ссылочных атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута не равно значению условия в фильтре.
GREATER подходит для числовых атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута больше значения условия в фильтре.
GREATER_OR_EQUAL подходит для числовых атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута больше или равно значению условия в фильтре.
LESS подходит для числовых атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута меньше значения условия в фильтре.
LESS_OR_EQUAL подходит для числовых атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута меньше или равно значению условия в фильтре.
CONTAINS подходит для строковых атрибутов. Результаты включают только те экземпляры сущностей, у которых значение атрибута содержит значение условия в фильтре.
NOT_CONTAINS подходит для строковых атрибутов. Результаты включают только те экземпляры сущностей, у которых значение атрибута не содержит значение условия в фильтре.
STARTS_WITH подходит для строковых атрибутов. Результаты включают только те экземпляры сущностей, у которых значение атрибута начинается со значения условия в фильтре.
ENDS_WITH подходит для строковых атрибутов. Результаты включают только те экземпляры сущностей, у которых значение атрибута заканчивается значением условия в фильтре.
IS_SET подходит для строковых, числовых, ссылочных атрибутов и атрибутов даты. Оператор проверяет только те значения атрибутов, которые не являются нулевыми. Компонент ComboBox, созданный для этой операции, отображает два значения: true и false. Если пользователь выбирает true, результаты включают только те экземпляры сущностей, у которых есть значение атрибута. В противном случае результаты включают только те экземпляры сущностей, у которых нет значения атрибута.
IN_LIST подходит для строковых, числовых, ссылочных атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута соответствует любому элементу списка.
NOT_IN_LIST подходит для строковых, числовых, ссылочных атрибутов и атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута не соответствует ни одному элементу списка.
DATE_INTERVAL подходит для атрибутов даты. Результаты включают только те экземпляры сущностей, у которых значение атрибута соответствует значению, заданному в Редакторе интервалов дат.

PropertyFilter может автоматически определять и отображать компонент для ввода значения согласно типу соответствующего свойства сущности и операции. Например, для строковых и числовых атрибутов приложение использует TextField, для Date – DateField, для enum значений – ComboBox, для ссылок на другие сущности – EntityPicker. Для IN_LIST и NOT_IN_LIST приложение использует компонент ValuesPicker.

PropertyFilter также поддерживает пользовательские компоненты UI в качестве его значения. Описать компонент UI можно внутри тега propertyFilter.

Например, вы можете использовать EntityComboBox вместо EntityPicker:

<data>
    <collection id="customersDc" class="ui.ex1.entity.Customer">
        <fetchPlan extends="_base">
            <property name="city" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="customersDl">
            <query>
                <![CDATA[select e from uiex1_Customer e]]>
            </query>
        </loader>
    </collection>
    <collection id="citiesDc" class="ui.ex1.entity.City">
        <fetchPlan extends="_base"/>
        <loader id="citiesDl">
            <query>
                <![CDATA[select e from uiex1_City e]]>
            </query>
        </loader>
    </collection>
</data>
<layout spacing="true" expand="customersTable">
    <propertyFilter property="city" operation="EQUAL" dataLoader="customersDl">
        <entityComboBox metaClass="uiex1_City" optionsContainer="citiesDc"/>
    </propertyFilter>
</layout>

Вы можете использовать EntityPicker с пользовательским экраном поиска, например:

<propertyFilter property="city" operation="EQUAL" dataLoader="customersDl">
    <entityPicker metaClass="uiex1_City">
        <actions>
            <action id="entityLookup" type="entity_lookup">
                <properties>
                    <property name="screenId" value="uiex1_City.browse"/>
                    <property name="openMode" value="DIALOG"/>
                </properties>
            </action>
        </actions>
    </entityPicker>
</propertyFilter>

Атрибут operationCaptionVisible определяет видимость заголовка операции. Возможные значения – true и false (по умолчанию true).

Используя атрибут operationEditable можно задать видимость селектора операции. Возможные значения – true и false. Значение по умолчанию – false. Если задать operationEditable = true, то поле операции позволит выбирать оператор условия во время выполнения. Список доступных операторов зависит от типа атрибута.

Условия даты

PropertyFilter имеет операцию DATE_INTERVAL. Для нее приложение использует компонент ValuePicker со специальным действием. Это позволяет отображать диалоговое окно для настройки интервала дат.

Автоматическое применение

Атрибут autoApply задает, должен ли фильтр свойств автоматически применяться к загрузчику данных при изменении значения условия. Значение по умолчанию – true.

Настройка Caption

С помощью атрибута caption можно задать собственные надписи для условий фильтра. Если значение не задано, то они генерируются автоматически на основе имени свойства сущности и ярлыка операции (если operationCaptionVisible установлено в true).

Если атрибут caption задан, то операция не отображается.

Атрибут captionPosition определяет расположение надписи: TOP или LEFT. Значение по умолчанию – LEFT.

Атрибут captionWidth задает фиксированную ширину надписи для PropertyFilter. Установите значение -1, чтобы использовать автоматический размер.

Значение по умолчанию

В атрибуте defaultValue можно установить значение по умолчанию для условия фильтра.

<propertyFilter property="age"
                defaultValue="30"
                operation="LESS_OR_EQUAL"
                dataLoader="customersDl">
</propertyFilter>

Имя параметра

Атрибут parameterName задает имя связанного параметра запроса, используемого условием. Если значение не задано, то имя параметра генерируется случайным образом.

Поддержка KeyValueCollectionContainer

PropertyFilter может быть привязан к KeyValueCollectionContainer, например:

<data>
    <keyValueCollection id="salesDc">
        <loader id="salesLoader">
            <query>
                <![CDATA[select o.customer, o.customer.firstName,
                sum(o.amount) from uiex1_Order o group by o.customer]]>
            </query>
        </loader>
        <properties>
            <property class="ui.ex1.entity.Customer" name="customerEntity"/>
            <property datatype="string" name="customerName"/>
            <property datatype="decimal" name="sum"/>
        </properties>
    </keyValueCollection>
</data>
<layout spacing="true" expand="customersTable">
    <propertyFilter property="customerEntity.firstName" operation="STARTS_WITH"
                    dataLoader="salesLoader" operationEditable="true"/>
    <propertyFilter property="customerName" operation="CONTAINS"
                    dataLoader="salesLoader" operationEditable="true"/>
</layout>

PropertyFilter не поддерживает свойства key-value, содержащие агрегатные функции (COUNT, SUM, AVG, MIN, MAX).

События и слушатели

Чтобы сгенерировать заглушку слушателя в Jmix Studio, выберите компонент в XML-дескрипторе экрана или на панели иерархии Jmix UI и используйте вкладку Handlers на панели инспектора Jmix UI.

В качестве альтернативы вы можете воспользоваться кнопкой Generate Handler на верхней панели контроллера экрана.

ContextHelpIconClickHandler

См. ContextHelpIconClickHandler.

OperationChangeEvent

OperationChangeEvent отправляется при изменении свойства operation. Пример подписки на событие propertyFilter, объявленного в XML с идентификатором hobbyFilter:

@Subscribe("hobbyFilter")
public void onHobbyFilterOperationChange(PropertyFilter.OperationChangeEvent event) {
    notifications.create()
            .withCaption("Before: " + event.getPreviousOperation() +
                    ". After: " + event.getNewOperation())
            .show();
}

Чтобы создать слушателя события программно, используйте метод компонента addOperationChangeListener().

ValueChangeEvent

ValueChangeEvent отправляется при изменении значения, когда пользователь завершил его ввод, например, после нажатия кнопки Enter или потере компонентом фокуса. ValueChangeEvent имеет следующие методы:

getPrevValue() возвращает значение компонента до изменения.
getValue() возвращает текущее значение компонента.

Пример подписки на событие propertyFilter, объявленного в XML с идентификатором hobbyFilter:

@Subscribe("hobbyFilter")
public void onHobbyFilterValueChange(HasValue.ValueChangeEvent event) {
    notifications.create()
            .withCaption("Before: " + event.getPrevValue() +
                    ". After: " + event.getValue())
            .show();
}

Чтобы создать слушателя события программно, используйте метод компонента addValueChangeListener().

Все XML-атрибуты

Просматривать и редактировать атрибуты, применимые к компоненту, можно с помощью панели инспектора Jmix UI в конструкторе экранов Studio.

align - autoApply - caption - captionAsHtml - captionPosition - captionWidth - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - dataLoader - defaultValue - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - operation - operationCaptionVisible - operationEditable - parameterName - property - required - requiredMessage - responsive - rowspan - stylename - tabIndex - visible - width