Filter (element)

From JRapid

Jump to: navigation, search

filter is an element, child of entity.


Contents

Description

Filters are used in listings so that users may apply searching criteria over the entity records.


They provide all the necessary application layers for filtering: UI elements, server side code and web services.

A filter is primarily defined by its mode. The mode is not an actual attribute of the filter, but a way of classifying the filter based on the elements used to define it and the resulting complexity.

Filter modes:

  • auto: filter the listing by the value of a property.
  • basic: allows to specify multiple conditions for properties.
  • advanced: filter by an HQL expression.
  • mixed: both basic and advanced mode.


The type attribute specifies the data type of the property on which the filter will be applied. If the property is of type entity, then the entity attribute should be used.

The property attribute indicates the property on which the filter will be applied. The flag attribute sets the way that the input text is matched to the field being filtered.

A widget attribute is used for setting the way the filter is displayed. See widgets section.

The collection attribute indicates that what is being filtered is a collection.

If the filter is an entity type filter, you may specify a subset for restricting the options shown in you filter widget.

The display attribute can take values:

  • primary: filter is shown in listing as primary filter
  • secondary: filter is shown in listings as advanced filter. See example below for more on this.

Every filter generates a method in the corresponding DAO files for the entity. This method implements the necessary logic to build the query criteria. Take a look at the example below to see a more detailed explanation of this.

Usage

<entity
   ...
   <filter 
            name = NAME
            entity = ENTITY
            type = TYPE
            label = LABEL
            property = COLUMN_NAME
            subset = SUBSET
            flag = "contains | exact"
            widget = WIDGET
            display = "primary" | "secondary"
            collection = "list | set | sortedset"
            comboproperty = COMBOPROPERTY>
            [Contents: enum*, restriction*, and*, or*, condition* ]   
   </filter>
</entity>

Example

  • This is a simple example that involves a Company and a City entity. The Company listing companyListing includes three filters.

The filterName filter applies the search criteria over the name property. This property is of type string and, hence, the default generated filter is an input box that matches records starting with the value entered.

The filterActive filter is defined to use the active property of type boolean. This creates, by default, a filter with the options true, false and empty.

When a filter is created over a property of entity type, like the case of filterCity, a select element with the corresponding options is created. Note that, in this case, the filterCity filter uses a subset to restrict the records shown as options.

<entity label="Company" menu="People" name="Company">

        <subset displayproperties="name,city.name,active" name="forCompanyListing"/>
        <listing displayproperties="name,city.name,active" name="companyListing" subset="forCompanyListing"/>

        <filter display="primary" label="Name" name="filterName" property="name"/>
        <filter display="primary" label="Active" name="filterActive" property="active"/>
        <filter display="primary" label="City" name="filterCity" property="city" subset="forActiveCity"/>

        <property display="primary" label="Name" name="name"/>
        <property label="Address" name="address" type="text"/>
        <property display="secondary" entity="City" label="City" name="city"/>
        <property display="secondary" label="Active" name="active" type="boolean"/>
        <property display="secondary" label="Load Date" name="loadDate" type="date"/>
</entity>

<entity label="City" menu="Places" name="City" order="name">
        <subset name="forActiveCity" order="name">
            <condition field="active" value="true"/>
        </subset>

        <property display="primary" label="City" name="name"/>
        <property display="secondary" label="Active" name="active" type="boolean"/>
</entity>

The filters in action look like this.

Filters example


This filters generate all the necessary methods in the DAO code layer.

The CompanyDAOAbstract class contains this code:

public interface CompanyDAOAbstract extends DAO<Company> {
    ...
    public Filter getFilterNameFilter(String filterName);
    
    public Filter getFilterActiveFilter(Boolean filterActive);
    
    public Filter getFilterCityFilter(City filterCity);    
    ...
}

And the HibernateCompanyDAOAbstract class implements these methods:

public abstract class HibernateCompanyDAOAbstract extends HibernateDAO<Company> implements CompanyDAOAbstract {
    ...
    // filters    
    
    @FilterMethod("filterName")
    public Filter getFilterNameFilter(String filterName) {
        return new HibernateFilter("me.name LIKE CONCAT(?, '%')", filterName);
    }
    
    @FilterMethod("filterActive")
    public Filter getFilterActiveFilter(Boolean filterActive) {
        return new HibernateFilter("me.active = ?", filterActive);
    }
    
    @FilterMethod("filterCity")
    public Filter getFilterCityFilter(City filterCity) {
        return new HibernateFilter("me.city = ?", filterCity);
    }
    ...   
}


  • A little more complex example is described here. The entity HarvestedCrops has a field and a harvestDate properties, and two filters are created. One filters the records based on the chosen field, the other filters taking a date and showing only the records with the same month and year as the value entered.
<entity label="Production Field" menu="Menu" name="ProductionField">
    <property display="primary" label="Name" name="name"/>
    <property label="Description" name="description" type="text"/>
</entity>

<entity label="Harvested Crops" menu="Menu" name="HarvestedCrops" order="harvestDate">
    <property display="primary" entity="ProductionField" label="Field" name="field"/>
    <property display="primary" label="Date" name="harvestDate" type="date" widget="jdatepicker"/>
    <property display="secondary" label="Production (Tonnes)" name="production" type="long"/>
    <filter display="primary" label="Field Filter" name="fieldFilter" property="field"/>
    <filter display="primary" label="Month Filter" name="monthFilter" type="date">
        <restriction expr="(month(harvestDate) = month(?) and year(harvestDate) = year(?))">
            <param value="monthFilter"/>
            <param value="monthFilter"/>
        </restriction>
    </filter>
</entity>

A simple filter is created on the field property of entity type ProductionField.

Another filter is created over the harvestDate property, of type date. This filter takes the date value entered in the filter input and applies a same month and year criteria on the existing records through the use of a restriction. The value entered in the filter input is used to set the two parameters. This is done using the name of the filter as the entered value. The param elements are then used in the expression like positional parameters.


  • A short example showing the use of the display attribute and how filters are shown on a listing according to this. A link to "Advanced filters" is added below the primary filters. When clicked, this link toggles the visibility of the secondary filters.
    <entity label="Company" menu="Menu" name="Company">
        <property display="primary" label="Name" name="name"/>
    </entity>

    <entity label="Contact" menu="Menu" name="Contact">
        <property display="primary" label="First Name" name="firstName"/>
        <property display="primary" label="Last Name" name="lastName"/>
        <property display="secondary" entity="Company" label="Company" name="company"/>
        <property label="Phone" name="phone"/>
        <property label="Email" name="email"/>
        <property label="Mobile" name="mobile"/>
        <property label="Comments" name="comments" type="text"/>

        <filter display="primary" label="Last Name" name="lastNameFilter" property="lastName"/>
        <filter display="primary" label="Company" name="companyFilter">
            <condition field="company.name" like="companyFilter"/>
        </filter>
        <filter display="secondary" label="Phone" name="phoneFilter" property="phone"/>
        <filter display="secondary" label="Email" name="emailFilter" property="email"/>
    </entity>


Filter display attribute example

See also

Personal tools