CUBA Platform. Developer's Manual
4.5.2.1.9. Filter

include – required attribute. It contains a regular expression, which should match an entity attribute name.

exclude – contains a regular expression. If an attribute matches the expression, it will be excluded from previously included (using include).

Collections (@OneToMany, @ManyToMany).

Attributes which do not have localized names.

The version attribute.

name – rrequired attribute, containing the name of entity attribute to be included. It can be a path (using ".") in the entity graph. For example:

<filter id="transactionsFilter" datasource="transactionDs" applyTo="table">
    <properties include=".*" exclude="(masterTransaction)|(authCode)"/>
    <property name="creditCard.maskedPan" caption="msg://EmbeddedCreditCard.maskedPan"/>
    <property name="creditCard.startDate" caption="msg://EmbeddedCreditCard.startDate"/>
</filter>

caption – localized entity attribute name displayed in filter conditions. Generally it is a string with the msg:// prefix in accordance with MessageTools.loadString() rules.

If the name attribute is specified as an entity graph path (using ".") , the caption attribute is required.

paramWhere − specifies the JPQL expression which is used to select the list of condition parameter values if the parameter is a related entity. The {E} placeholder should be used in the expression instead of the alias of the entity being selected.

For example, let us assume that Car has a reference to Model. Then possible condition parameter values list can be limited to Audi models only:

<filter id="carsFilter" datasource="carsDs">
    <property name="model" paramWhere="{E}.manufacturer = 'Audi'"/>
</filter>

Screen parameters, session attributes and screen components including those showing other parameters can be used in JPQL expression. Query parameters specification rules are described in Section 4.5.3.2, “CollectionDatasourceImpl Queries”.

An example of session and screen parameters usage is shown below:

{E}.createdBy = :session$userLogin and {E}.name like :param$groupName

With the paramWhere clause, you can introduce dependencies between parameters. For example, let us assume that Manufacturer is a separate entity. That is Car has a reference to Model which in turn has a reference to Manufacturer. Then you may want to create two conditions for the Cars filter: first to select a Manufacturer and second to select a Model. To restrict the list of models by previously selected manufacturer, add a parameter to the paramWhere expression:

{E}.manufacturer.id = :component$filter.model_manufacturer90062

The parameter references a component which displays Manufacturer parameter. You can see the name of the component showing condition parameter by opening context menu on a condition table row in the filter editor:

paramView − specifies a view, which will be used to load the list of condition parameter values if the parameter is a related entity. For example, _local. If view is not specified, _minimal view will be used.

name − required attribute, condition name.

caption − required attribute, localized condition name. Generally it is a string with the msg:// prefix in accordance with MessageTools.loadString() rules.

paramClass − Java class of the condition parameter. If the parameter is not specified, this attribute is optional.

inExpr − should be set to true, if the JPQL expression contains in (?) conditions. In this case user will be able to enter several condition parameter values.

join − optional attribute. It specifies a string, which will be added to the data source query from section. This can be required to create a complex condition based on an attribute of a related collection. join or left join statements should be included into the attribute value.

For example, let us assume that the Car entity has a repairs attribute, which is a related entity Repair instances collection. Then the following condition can be created to filter Car by Repair entity's description attribute:

<filter id="carsFilter" datasource="carsDs">
    <custom name="repair"
            caption="msg://repair"
            paramClass="java.lang.String"
            join="join {E}.repairs cr">
        cr.description like ?
    </custom>
</filter>

If the condition above is used, the original data source query

select c from sample$Car c order by c.createTs

will be transformed into the following one:

select c from sample$Car c join c.repairs cr
where (cr.description like ?)
order by c.createTs

paramWhere − specifies a JPQL expression used to select the list of condition parameter values if the parameter is a related entity. See the description of the property element's attribute of the same name.

paramView − specifies a view, which will be used when a list of condition parameter values are loaded if the parameter is a related entity. For example, _local. If it is not specified, _minimal view will be used.