Filtering configuration reference

There are several ways of applying filters to grid columns, and each method offers a number of operators. Filters applied in the code can be combined using logical and and or operators.

Operators

The table below gives a comparison of the operators available in each method.

caplin.grid.GridColumnFilter operator caplin.component.filter.FieldFilterExpression

LESS_THAN

<

LESS_THAN

GREATER_THAN

>

GREATER_THAN

EXACT_MATCH

=

EQUAL

PARTIAL_MATCH

WILDCARD

WILDCARD_CASE_SENSITIVE

REGULAR_EXPRESSION

~

REGULAR_EXPRESSION

REGULAR_EXPRESSION_CASE_INSENSITIVE

#

CASE_INSENSITIVE_REGULAR_EXPRESSION

LESS_THAN_OR_EQUAL

<=

LESS_THAN_OR_EQUAL

GREATER_THAN_OR_EQUAL

>=

GREATER_THAN_OR_EQUAL

NUMERIC_MATCH

NUMERIC_EQUAL

!=

NOT_EQUAL

User Filters and HTML Escape Codes

Users can, if the correct renderer is applied to a column, apply a filter to a column themselves, although they can only apply one filter at a time. When users enters a filter, they would use commonly recognised symbols for their operators (">" for greater than, "⇐" for less than or equal, and so on). The operator attribute in the <fieldFilter> tag uses the same symbols, but has to replace the > and < symbols with HTML escape codes (or "entity reference codes" if you prefer), to prevent errors. Full details of how to set up user filtering are available in How Can I Configure Sorting and Filtering.

caplin.grid.GridColumnFilter

The caplin.grid.GridColumnFilter class can be used to set up a particular filter. You cannot combine filter conditions using this class, and should use a different filtering method if you need to do that. You could try to make a complex filter using a regular expression if you were so inclined, but it’s probably easier to use <filterExpression> tags in the XML, or to use the caplin.component.filter.FieldFilterExpression class instead.

Constructor Summary

caplin.grid.GridColumnFilter(<string> sFilterField, <int> nFilterType, <string> sFilterValue)

  • filterField (often expressed as sFilterField): the field (column) of the grid, on which the filter is to be applied.

  • filterType (often expressed as nFilterType): the filter operator being applied to the column, which will be taken from the list below.

  • filterValue (often expressed as sFilterValue): the value against which the filterField is being compared.

Available Operators

Operator Description

LESS_THAN

Only displays rows in which filterField is less than filterValue

GREATER_THAN

Only displays rows in which filterField is greater than filterValue

EXACT_MATCH

Only displays rows in which filterField is exactly the same as filterValue

PARTIAL_MATCH

Only displays rows in which filterValue is contained within filterField.

WILDCARD

Only displays rows in which filterField matches the filterValue string, using * as a wildcard, regardless of case.

Note: wildcards are converted from "" to "." and sent to Caplin Refiner as regular expressions, for the filters to be applied.

WILDCARD_CASE_SENSITIVE

As above, but the filter is case-sensitive.

REGULAR_EXPRESSION

Only displays rows in which filterField matches a regular expression contained in the filterValue string, using the syntax for Java regular expressions.

REGULAR_EXPRESSION_CASE_INSENSITIVE

As above, but the filter is case-sensitive.

LESS_THAN_OR_EQUAL

Only displays rows in which filterField is less than or equal to filterValue

GREATER_THAN_OR_EQUAL

Only displays rows in which filterField is greater than or equal to filterValue

NUMERIC_MATCH

Only displays rows in which filterField has the same numerical value as filterValue

Code Sample

function filterGrid(columnIndex)
{
    var gridColumn = this.gridColumnModel.getColumnByIndex(columnIndex);

    gridColumn.addFilter(caplin.grid.GridColumnFilter.GREATER_THAN, "5");
}

caplin.component.filter.FieldFilterExpression

The caplin.component.filter.FieldFilterExpression class is an implementation of the caplin.component.filter.FilterExpression interface. You can use in in conjunction with the caplin.component.filter.LogicalFilterExpression class, in order to combine filters with logical AND and OR operators, as explained below.

Constructor Summary

caplin.component.filter.FieldFilterExpression(<String> sFieldName, <String> sOperator, <String> sValue, sPrimaryFieldType)

  • fieldName (often expressed as sFieldName): the field (column) of the grid, on which the filter is to be applied.

  • operator (often expressed as sOperator): the filter operator being applied to the column, which will be one of the values provided for by caplin.component.filter.FieldFilterExpression.Operator; listed below.

  • value (often expressed as sValue): the value against which the fieldName is being compared.

Available Operators

Operator Description

LESS_THAN

Only displays rows in which fieldName is less than value

GREATER_THAN

Only displays rows in which fieldName is greater than value

EQUAL

Only displays rows in which fieldName is identical to the value

REGULAR_EXPRESSION

Only displays rows in which fieldName matches a regular expression contained in the value string, using the syntax for Java regular expressions.

CASE_INSENSITIVE_REGULAR_EXPRESSION

As above, but not case sensitive.

LESS_THAN_OR_EQUAL

Only displays rows in which fieldName is less than or equal to value

GREATER_THAN_OR_EQUAL

Only displays rows in which fieldName is greater than or equal to value

NOT_EQUAL

Only displays rows in which fieldName does not match value

NUMERIC_EQUAL

Only displays rows in which fieldName is numerically equal to value

Code Sample

Example of a standalone FieldFilterExpression, where rows will be displayed if Bid > 100

var oFilter = new caplin.component.filter.FieldFilterExpression("Bid", caplin.component.filter.FieldFilterExpression.Operator.GREATER_THAN, "100");

Combining Filters with Logical Operators

The caplin.component.filter.FilterExpression interface also provides a caplin.component.filter.LogicalFilterExpression class, with two logical operators: AND, and OR. These can be used to combine standard filter expressions, like this:

var oFilter = new caplin.component.filter.LogicalFilterExpression(caplin.component.filter.LogicalFilterExpression.Operator.AND);
oFilter.addFilterExpression(new caplin.component.filter.FieldFilterExpression("Bid", caplin.component.filter.FieldFilterExpression.Operator.GREATER_THAN, "100"));
oFilter.addFilterExpression(new caplin.component.filter.FieldFilterExpression("Bid", caplin.component.filter.FieldFilterExpression.Operator.LESS_THAN, "105"));

This would display files in which the value of the "Bid" field was greater than 100 but less than 105.

You can also make more complex filters by combining multiple logical operators to create compound logical filter expressions. For example:

var oFilter = new caplin.component.filter.LogicalFilterExpression(caplin.component.filter.LogicalFilterExpression.Operator.OR);

var oSubFilter1 = new caplin.component.filter.LogicalFilterExpression(caplin.component.filter.LogicalFilterExpression.Operator.AND);
oSubFilter1.addFilterExpression(new caplin.component.filter.FieldFilterExpression("Bid", caplin.component.filter.FieldFilterExpression.Operator.GREATER_THAN, "100"));
oSubFilter1.addFilterExpression(new caplin.component.filter.FieldFilterExpression("Bid", caplin.component.filter.FieldFilterExpression.Operator.LESS_THAN, "105"));

var oSubFilter2 = new caplin.component.filter.LogicalFilterExpression(caplin.component.filter.LogicalFilterExpression.Operator.AND);
oSubFilter2.addFilterExpression(new caplin.component.filter.FieldFilterExpression("BidYield", caplin.component.filter.FieldFilterExpression.Operator.GREATER_THAN, "5.5"));
oSubFilter2.addFilterExpression(new caplin.component.filter.FieldFilterExpression("BidYield", caplin.component.filter.FieldFilterExpression.Operator.LESS_THAN, "8.5"));

oFilter.addFilterExpression(oSubFilter1);
oFilter.addFilterExpression(oSubFilter2);

This example would display rows in which either the "Bid" column was greater than 100 and less than 105, or the "BidYield" column was greater than 5.5 and less than 8.5.

XML fieldFilter Element

Filters can be set up within an XML grid definition, in the gridDefinitions.xml file. You would need to add a <fieldFilter> element into the <gridRowModel> element of the grid you want to filter. You can then add any filter conditions you want to apply, in the form of <fieldFilter> tags. Boolean conditions, in the form of <and> and <or> tags, can be applied, to allow multiple conditions to be combined within the same grid.

fieldFilter Attributes

The <fieldfilter> tag is an empty element, and has three attributes, to enable you to define a filter condition:

  • field: the name of the field on which the filter is to be applied. If caplin.grid.RttpContainerGridDataProvider is being used as a data provider, this will be an RTTP fieldname, and should match the fields attribute within the appropriate <column> tag, in the grid definition.

  • operator: the filter operator to be applied to the specified field (column). The available operators are listed in the table below.

  • value: the value against which the specified field is being compared.

Available Operators

Operator Equivalent FieldFilterExpression Operator Description

<

LESS_THAN

Only displays rows in which field is less than value

>

GREATER_THAN

Only displays rows in which field is greater than value

=

EQUAL

Only displays rows in which field is identical to the value

~

REGULAR_EXPRESSION

Only displays rows in which field matches a regular expression contained in the value string, using the syntax for Java regular expressions.

#

CASE_INSENSITIVE_REGULAR_EXPRESSION

As above, but not case sensitive.

<=

LESS_THAN_OR_EQUAL

Only displays rows in which field is less than or equal to value

>=

GREATER_THAN_OR_EQUAL

Only displays rows in which field is greater than or equal to value

!=

NOT_EQUAL

Only displays rows in which field does not match value
The standard "greater-than" and "less-than" symbols are replaced with their equivalent HTML escape codes, so as not to clash with the angle-brackets on element names.

Code Sample

The example below shows a single <fieldFilter> tag, which sets a filter to display only rows in which the "Bid" column contains a value greater than or equal to 1000.

<grid>
    ...
    <gridRowModel>
    ...
    <filterExpression>
        <fieldFilter field="Bid" operator="&gt;=" value="1000" />
    </filterExpression>
    </gridRowModel>
</grid>

Combining Filters with <and> and <or> Tags

Filters defined using <fieldFilter> in the grid definition can be combined by placing multiple <fieldFilter> elements within <and> and <or> tags, like so:

<grid>
   ...
   <gridRowModel>
    ...
    <filterExpression name="myFilter">
       <and>
        <fieldFilter field="Bid" operator="&gt;" value="100"/>
        <fieldFilter field="Bid" operator="&lt;" value="105"/>
       </and>
    </filterExpression>
   </gridRowModel>
</grid>

This would display files in which the value of the "Bid" field was greater than 100 but less than 105.

You can also create compound logical filters by nesting them, as in the example below:

<filterExpression name="myFilter">
    <or>
       <and>
        <fieldFilter field="Bid" operator="&gt;" value="100"/>
        <fieldFilter field="Bid" operator="&lt;" value="105"/>
       </and>
       <and>
        <fieldFilter field=" BidYield " operator="&gt;" value="5.5"/>
        <fieldFilter field=" BidYield " operator="&lt;" value="8.5"/>
       </and>
  </or>
</filterExpression>

This example would display rows in which either the "Bid" column was greater than 100 and less than 105, or the "BidYield" column was greater than 5.5 and less than 8.5.