propertyFilter

LIVE DEMO

propertyFilter defines a filtering condition based on a particular property of an entity.

The component can be used inside the genericFilter component or independently.

  • XML element: propertyFilter

  • Java class: PropertyFilter

Basics

In the general case, propertyFilter consists of a label with the entity property caption, operation label or selector (=, contains, in, >, etc.), and a field for editing a condition value.

property filter basics

The example of the propertyFilter declaration is provided below.

<data>
    <collection class="com.company.onboarding.entity.User" id="usersDc">
        <fetchPlan extends="_base">
            <property name="department" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="usersDl">
            <query>
                <![CDATA[select e from User e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
    <propertyFilter dataLoader="usersDl"
                    operation="EQUAL"
                    property="department"/>
</layout>

dataLoader, property, and operation are required attributes.

You can use multiple propertyFilter components connected to one data loader. Thus, filtering can be performed according to several conditions.

Attributes

id - alignSelf - autoApply - classNames - colspan - dataLoader - defaultValue - enabled - errorMessage - height - helperText - invalid - label - labelPosition - labelVisible - labelWidth - maxHeight - maxWidth - minHeight - minWidth - operation - operationEditable - operationTextVisible - parameterName - property - readOnly - required - requiredIndicatorVisible - requiredMessage - tabIndex - themeNames - visible - width

autoApply

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

dataLoader

dataLoader is a required attribute. It sets a data loader related to the current propertyFilter.

defaultValue

Sets the default value for the filter condition.

label

Sets the custom label of the property filter condition. If not specified, it is generated automatically based on the entity property caption and the operation label.

If you set the label attribute, the operation label or selector will not be displayed.

labelPosition

The labelPosition attribute defines the filter label position:

  • TOP - label is displayed atop the property filter.

  • ASIDE - label is displayed on the side of the property filter.

The default value is ASIDE.

labelVisible

Sets the label visible or not. Default value is true.

labelWidth

Sets the label width. The width should be in a format understood by the browser, for example, "100px" or "2.5em".

operation

operation is a required attribute. It sets a filtering operation. The operation can be of the following types:

  • EQUAL is suitable for string, numeric, boolean, date/time, reference and enum attributes. Results include only entity instances where the data in the property column matches the condition value in the filter.

  • NOT_EQUAL is suitable for string, numeric, boolean, date/time, reference and enum attributes. Results include only entity instances where the data in the property column does not match the condition value in the filter.

  • GREATER is suitable for numeric and date/time attributes. Results include only entity instances where the data in the property column is greater than the condition value in the filter.

  • GREATER_OR_EQUAL is suitable for numeric and date/time attributes. Results include only entity instances where the data in the property column is greater than or the same as the condition value in the filter.

  • LESS is suitable for numeric and date/time attributes. Results include only entity instances where the data in the property column is less than the condition value in the filter.

  • LESS_OR_EQUAL is suitable for numeric and date/time attributes. Results include only entity instances where the data in the property column is less than or the same as the condition value in the filter.

  • CONTAINS is suitable for string attributes. Results include only entity instances where the data in the property column has the condition value in the filter.

  • NOT_CONTAINS is suitable for string attributes. Results include only entity instances where the data in the property column does not contain the condition value in the filter.

  • STARTS_WITH is suitable for string attributes. Results include only entity instances where the data in the property column begins with the condition value in the filter.

  • ENDS_WITH is suitable for string attributes. Results include only entity instances where the data in the property column ends with the condition value in the filter.

  • IS_SET is suitable for string, numeric, boolean, date/time, reference and enum attributes. The operator tests only the data in the property column that are not null. The comboBox component, generated for this operation, displays two values: Yes and No. If the user selects Yes, results include only entity instances where there is data in the column. Otherwise, results include only entity instances where there is no data in the column.

operationEditable

Sets whether an operation selector is visible. Possible values are true and false. The default value is false. If you set operationEditable = true, the operation field enables selecting the condition operator in run-time. The list of available operators depends on the attribute type.

operationTextVisible

The operationTextVisible attribute defines the visibility of the operation label. Possible values are true and false (true by default).

parameterName

The parameterName attribute sets the name of the associated query parameter name, used by condition. If not defined, then the parameter name is randomly generated.

property

Sets the related entity property name or properties path (for example, name, order, order.date).

Handlers

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent - OperationChangeEvent - validator

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the Code → Generate menu (Alt+Insert / Cmd+N).

OperationChangeEvent

The OperationChangeEvent is sent when the operation property is changed.

validator

Adds a validator instance to the component. The validator must throw ValidationException if the value is not valid.

If you are not satisfied with the predefined validators, add your own validator instance:

@Install(to = "propertyFilter", subject = "validator")
private void propertyFilterValidator(String value) {
    if (value != null && value.length() != 6)
        throw new ValidationException("Zip must be of 6 digits length");
}

Elements

tooltip - validator