propertyFilter

propertyFilter filters data by an attribute of an entity.

XML Element

propertyFilter

Java Class

PropertyFilter

Basics

LIVE DEMO

At its simplest, propertyFilter consists of an input field preceded by the name of the property being filtered and the operation being used.

<data>
    <collection id="ordersDc"
                class="io.jmix.uisamples.entity.Order"
                fetchPlan="_local">
        <loader id="ordersDl">
            <query>
                <![CDATA[select e from uisamples_Order e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <propertyFilter property="amount"
                    operation="GREATER_OR_EQUAL"
                    dataLoader="ordersDl"/>
    <dataGrid id="orderDataGrid"
              dataContainer="ordersDc"
              width="100%"
              minHeight="20em">
        <columns>
            <column property="date"/>
            <column property="customer"/>
            <column property="amount"/>
            <column property="description"/>
        </columns>
    </dataGrid>
</layout>

This component filters data loaded to a data container. It is commonly used in conjunction with dataGrid or treeDataGrid components, which are bound to the same container. This combination allows for precise control over the rows displayed.

Filtering Operations

LIVE DEMO

The component supports numerous filtering operations. You can limit it to a specific operation or allow users to choose the operation they want at runtime using the operationEditable attribute.

<data>
    <collection id="customersDc"
                class="io.jmix.uisamples.entity.Customer"
                fetchPlan="_local">
        <loader id="customersDl">
            <query>
                <![CDATA[select e from Customer e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <propertyFilter id="propertyFilter"
                    property="name"
                    operation="CONTAINS"
                    operationEditable="true"
                    dataLoader="customersDl"/>
    <dataGrid id="customersDataGrid"
              dataContainer="customersDc"
              width="100%"
              minHeight="20em">
        <columns>
            <column property="name"/>
            <column property="lastName"/>
            <column property="age"/>
            <column property="active"/>
            <column property="grade"/>
        </columns>
    </dataGrid>
</layout>

The list of available operations depends on the property type.

Data-aware propertyFilter

Set dataLoader to the loader that propertyFilter should constrain and property to the entity attribute used in the condition. The loader can populate either a collection container or a key-value container.

Property Filter with a Collection Container

LIVE DEMO

The following example demonstrates setting up propertyFilter to work with a collection container:

<data>
    <collection id="ordersDc"
                class="io.jmix.uisamples.entity.Order"
                fetchPlan="_local">
        <loader id="ordersDl">
            <query>
                <![CDATA[select e from uisamples_Order e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <propertyFilter property="amount"
                    operation="GREATER_OR_EQUAL"
                    dataLoader="ordersDl"/>
    <dataGrid id="orderDataGrid"
              dataContainer="ordersDc"
              width="100%"
              minHeight="20em">
        <columns>
            <column property="date"/>
            <column property="customer"/>
            <column property="amount"/>
            <column property="description"/>
        </columns>
    </dataGrid>
</layout>

Property Filter with a Key-Value Collection Container

LIVE DEMO

The following example demonstrates setting up propertyFilter to work with a key-value collection container:

<data>
    <keyValueCollection id="customersDc">
        <loader id="customersDl">
            <query>
                <![CDATA[select o.customer.name, o.customer.lastName, sum(o.amount) from uisamples_Order o group by o.customer]]>
            </query>
        </loader>
        <properties>
            <property datatype="string" name="name"/>
            <property datatype="string" name="lastName"/>
            <property datatype="decimal" name="sum"/>
        </properties>
    </keyValueCollection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <propertyFilter id="propertyFilter"
                    label="Name contains"
                    property="name"
                    operation="CONTAINS"
                    dataLoader="customersDl"/>
    <dataGrid id="customersDataGrid"
              dataContainer="customersDc"
              width="100%"
              minHeight="20em">
        <columns>
            <column property="name"
                    header="Name"/>
            <column property="lastName"
                    header="Last name"/>
            <column property="sum"
                    header="Sum"/>
        </columns>
    </dataGrid>
</layout>

Multi-Filtering

Binding multiple propertyFilter components to a single data container allows to apply several conditions simultaneously. For example, use two components to support filtering by department and last name:

<hbox>
    <propertyFilter dataLoader="usersDl"
                    operation="EQUAL"
                    property="department"/>
    <propertyFilter dataLoader="usersDl"
                    operation="CONTAINS"
                    property="lastName"/>
</hbox>

Filtering Dates

Omitting Time

An exact match with = may not always fit Date/Time properties. Many situations require filtering by just the date, ignoring the time. In such cases, use date equals instead:

Date Interval

LIVE DEMO

The component provides several options to filter by date intervals. Choose the in interval operator and enter interval values in the dialog.

Choose from:

  • Last: intervals like "last 3 months" or "last 12 weeks".

  • Next: intervals such as "next 3 years" or "next 48 hours".

  • Predefined: quick selections including "today", "tomorrow", "this month", or "this year".

  • Relative date and time: for conditions like "by the end of the day", "at the start of the hour", "not the last day of the year".

  • Custom: for any start and end date. The start date is included in the range, the end date is excluded.

<data>
    <collection id="ordersDc"
                class="io.jmix.uisamples.entity.Order"
                fetchPlan="_local">
        <loader id="ordersDl">
            <query>
                <![CDATA[select e from uisamples_Order e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <propertyFilter property="date"
                    operation="IN_INTERVAL"
                    dataLoader="ordersDl"/>
    <dataGrid id="orderDataGrid"
              dataContainer="ordersDc"
              width="100%"
              minHeight="20em">
        <columns>
            <column property="date"/>
            <column property="customer"/>
            <column property="amount"/>
            <column property="description"/>
        </columns>
    </dataGrid>
</layout>

Customization

LIVE DEMO

You can explicitly specify the component to use as the input field and set its attributes. This enables to change the default propertyFilter look and feel and enhance it with additional features. For example:

<data>
    <collection id="ordersDc"
                class="io.jmix.uisamples.entity.Order">
        <fetchPlan extends="_local">
            <property name="customer" fetchPlan="_local"/>
        </fetchPlan>
        <loader id="ordersDl">
            <query>
                <![CDATA[select e from uisamples_Order e]]>
            </query>
        </loader>
    </collection>
    <collection id="customersDc"
                class="io.jmix.uisamples.entity.Customer">
        <fetchPlan extends="_local"/>
        <loader id="customersDl">
            <query>
                <![CDATA[select e from Customer e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <propertyFilter property="customer"
                    operation="EQUAL"
                    dataLoader="ordersDl">
        <entityComboBox metaClass="Customer" itemsContainer="customersDc">
            <actions>
                <action id="lookup" type="entity_lookup"/>
                <action id="clear" type="entity_clear"/>
            </actions>
        </entityComboBox>
    </propertyFilter>
    <dataGrid id="ordersDataGrid"
              dataContainer="ordersDc"
              width="100%"
              minHeight="20em">
        <columns>
            <column property="date"/>
            <column property="customer"/>
            <column property="amount"/>
            <column property="description"/>
        </columns>
    </dataGrid>
</layout>

Dynamic Attributes

The component supports filtering by dynamic attributes. This does not require having the dynamicAttributes facet on that view.

To specify a dynamic attribute, begin its name with a + prefix:

<propertyFilter
        property="+passengerNumberOfSeats"
        operation="EQUAL"
        dataLoader="carsDl"/>
If the dynamic attribute is an entity, it cannot be filtered through its attributes.

Theme Variants

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

No predefined variants

propertyFilter does not define built-in theme variants. Use themeNames for custom styles in your application theme.

Custom themes

Attributes

The following attributes are specific to propertyFilter:

Name Description Default

autoApply

Sets whether the property filter should be automatically applied to the DataLoader when the condition value is changed.

—

dataLoader

dataLoader is a required attribute.

—

defaultValue

Sets the default value for the filter condition.

—

label

Sets the component label.

—

labelPosition

The labelPosition attribute defines the filter label position:

—

labelVisible

Sets the label visible or not.

—

labelWidth

Sets the label width.

—

operation

Specifies the filtering operation.

—

operationEditable

Sets whether an operation selector is visible.

—

operationTextVisible

The operationTextVisible attribute defines the visibility of the operation label.

—

parameterName

The parameterName attribute sets the name of the associated query parameter name, used by condition.

—

property

Specifies the entity attribute bound to the component.

—

The following shared attributes are supported by propertyFilter:

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - enabled - errorMessage - focusShortcut - height - helperText - invalid - maxHeight - maxWidth - minHeight - minWidth - readOnly - required - requiredMessage - tabIndex - themeNames - visible - width

Handlers

The following handlers are specific to propertyFilter:

Name Description

OperationChangeEvent

The OperationChangeEvent is sent when the operation property is changed.

validator

Validates the component value.

The following shared handlers are supported by propertyFilter:

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent

Elements

A propertyFilter can include tooltip and validator as its nested elements.