Filter Components

Filter can use special filter components as conditions. Filter components should implement the FilterComponent interface.

There are three filter components available by default:

You can register your own filter component, see Filter Component Registration.

PropertyFilter

The PropertyFilter component can be used inside the Filter component and independently.

The example below demonstrates how to create a design-time configuration with a PropertyFilter:

<data>
    <collection id="customersDc" class="ui.ex1.entity.Customer">
        <fetchPlan extends="_base">
            <property fetchPlan="_base" name="city"/>
            <property name="favouriteBrands" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="customersDl">
            <query>
                <![CDATA[select e from uiex1_Customer e]]>
            </query>
        </loader>
    </collection>
</data>
<layout spacing="true" expand="customersTable">
            <filter dataLoader="customersDl"
                    id="filterPropertyFilter"
                    caption="PropertyFilter variations">
                <properties include=".*"/>
                <configurations>
                    <configuration id="propertyConfiguration"
                                   default="true"
                                   name="PropertyFilter">
                        <propertyFilter property="age"
                                        operation="GREATER_OR_EQUAL"
                                        operationEditable="true"/>
                    </configuration>
                </configurations>
            </filter>
</layout>

See the additional information in PropertyFilter.

JpqlFilter

JpqlFilter is a UI component used for filtering entities returned by the DataLoader. The component contains JPQL expressions that will be added to the from and where data loader query sections. The component can automatically render the proper layout for setting a condition value. A JpqlFilter layout contains a label with a caption and a field for editing a condition value in the general case. The component can be used only inside the Filter component.

The example below demonstrates how to create a design-time configuration with a JpqlFilter:

<window xmlns="http://jmix.io/schema/ui/window"
        caption="msg://filterScreen.caption"
        xmlns:c="http://jmix.io/schema/ui/jpql-condition"> (1)
    <data>
        <collection id="customersDc" class="ui.ex1.entity.Customer">
            <fetchPlan extends="_base">
                <property fetchPlan="_base" name="city"/>
                <property name="favouriteBrands" fetchPlan="_base"/>
            </fetchPlan>
            <loader id="customersDl">
                <query>
                    <![CDATA[select e from uiex1_Customer e]]>
                </query>
            </loader>
        </collection>
    </data>
    <layout spacing="true" expand="customersTable">
                <filter id="filterJpqlFilter"
                        dataLoader="customersDl"
                        caption="JpqlFilter variations">
                    <properties include=".*"/>
                    <configurations>
                        <configuration id="jpqlConfiguration"
                                       default="true"
                                       name="JpqlFilter">
                            <jpqlFilter caption="Name like"
                                        parameterClass="java.lang.String">
                                <condition>
                                    <c:jpql>
                                        <c:where>{E}.firstName like ?</c:where> (2)
                                    </c:jpql>
                                </condition>
                            </jpqlFilter>
                        </configuration>
                    </configurations>
                </filter>
    </layout>
</window>
1 You should add the JPQL conditions namespace.
2 Define a JPQL condition with optional join element and mandatory where element.

To configure JPQL conditions, define the condition element inside jpqlFilter with optional join element and mandatory where element. In the example below, we create jpqlFilter with the join and where elements:

<filter id="filterJpqlFilter"
        dataLoader="customersDl"
        caption="JpqlFilter variations">
    <properties include=".*"/>
    <configurations>
        <configuration id="jpqlConfigurationWithJoin"
                       name="JpqlFilter with Join">
            <jpqlFilter caption="Customers with brand"
                        parameterClass="ui.ex1.entity.Brand">
                <condition>
                    <c:jpql>
                        <c:join>join {E}.favoriteBrands i</c:join>
                        <c:where>i.id = ?</c:where>
                    </c:jpql>
                </condition>
            </jpqlFilter>
        </configuration>
    </configurations>
</filter>

jpqlFilter attributes inside the filter component:

  • You can set the condition name displayed in filter, using the caption attribute.

  • The hasInExpression attribute should be set to true if the JPQL expression contains in (?) conditions. In this case, the application will use the ValuesPicker component. So the user will be able to enter several condition parameter values.

    Below is an example of jpqlFilter with the hasInExpression attribute:

    <filter id="filterJpqlFilter"
        dataLoader="customersDl"
        caption="JpqlFilter variations">
    <properties include=".*"/>
    <configurations>
        <configuration id="jpqlConfigurationInExpr"
                       name="JpqlFilter with IN expression">
            <jpqlFilter caption="City in"
                        parameterClass="ui.ex1.entity.City"
                        hasInExpression="true">
                <condition>
                    <c:jpql>
                        <c:where>{E}.city in ?</c:where>
                    </c:jpql>
                </condition>
            </jpqlFilter>
        </configuration>
    </configurations>
</filter>

  • parameterClass is a required attribute; it defines the Java class of the condition parameter.

  • parameterName - the name of the associated query parameter. You can use this name to introduce dependencies between filter components in configuration. If not defined, then the parameter name is randomly generated.

GroupFilter

The GroupFilter component is a composite component that has a GroupBoxLayout with a ResponsiveGridLayout as its root container. This component is needed to combine several conditions into a logical group, using logical operators (AND or OR). The component can be used only inside the Filter component.

The example below demonstrates how to create a design-time configuration with a GroupFilter:

<filter id="filterGroupFilter"
        dataLoader="customersDl"
        caption="GroupFilter variations">
    <properties include=".*"/>
    <configurations>
        <configuration id="groupFilter"
                       name="Simple groupFilter"
                       default="true">
            <groupFilter operation="OR">
                <propertyFilter property="age"
                                operation="GREATER_OR_EQUAL"
                                operationEditable="true"/>
                <propertyFilter property="city"
                                operation="EQUAL"
                                operationEditable="true"/>
            </groupFilter>
        </configuration>
    </configurations>
</filter>

The operation attribute is required. Two logical operations are available:

  • AND is the default operation.

  • OR.

Filter Component Registration

To create and register a UI filter component in the framework, you need the following objects:

  • A component class - a UI component that will be displayed inside the Filter component. A component class should extend the FilterComponent class. As an example of a component class, consider the PropertyFilter class.

  • A model class - a non-persistent class that stores the state of the filter component. A model class is used to save the filter component state in DB and display and change the state of the filter component at run-time. A model class should extend the FilterCondition class. As an example of a model class, consider the PropertyFilterCondition class.

  • A converter class is needed for converting between a component and a model. A converter class should implement the FilterConverter interface.

  • An edit screen - the model edit screen. If no identifier is specified, then the default identifier (for example, modelName.edit, PropertyFilterCondition.edit) will be used.

PropertyFilter registration example:

@Bean
public FilterComponentRegistration registerPropertyFilter() {
    return FilterComponentRegistrationBuilder.create(PropertyFilter.class,
            PropertyFilterCondition.class,
            PropertyFilterConverter.class)
            .withEditScreenId("ui_PropertyFilterCondition.edit")
            .build();
}

All registered filter components are displayed in a popup button on the Add Condition dialog.

You can replace a filter component registered in the Jmix framework with your own implementation by specifying the @Order annotation on the FilterComponentRegistration bean (for example, to expand the set of model attributes saved by the filter).

All XML Attributes

You can view and edit attributes applicable to the component using the Component Inspector panel of the Studio’s Screen Designer.

PropertyFilter XML Attributes

See PropertyFilter XML Attributes.

JpqlFilter XML Attributes

align - caption - captionAsHtml - colspan - contextHelpText - contextHelpTextHtmlEnabled - css - defaultValue - description - descriptionAsHtml - editable - enable - box.expandRatio - hasInExpression - height - htmlSanitizerEnabled - icon - id - parameterClass - parameterName - required - requiredMessage - responsive - rowspan - stylename - tabIndex - visible - width

GroupFilter XML Attributes

align - caption - captionAsHtml - colspan - description - descriptionAsHtml - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - operation - operationCaptionVisible - responsive - rowspan - stylename - visible - width