# 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. The three ways of applying filters are to: * [Method comparison](#method-comparison) * [Use the caplin.grid.GridColumnFilter class](#user-filters-and-html-escape-codes) * [Use the caplin.component.filter.FieldFilterExpression class](#caplincomponentfilterfieldfilterexpression) * [Use the XML <fieldFilter> element](#xml-fieldfilter-element) ## Method comparison Each method is detailed separately below, along with the way in which different filters can be combined. 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 `` 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 `` tags in the XML, or to use the `caplin.component.filter.FieldFilterExpression` class instead. ### Constructor Summary ``` caplin.grid.GridColumnFilter( sFilterField, nFilterType, 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 ```js 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( sFieldName, sOperator, 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 ```js 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: ```js 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: ```js 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 `` element into the `` element of the grid you want to filter. You can then add any filter conditions you want to apply, in the form of `` tags. Boolean conditions, in the form of `` and `` tags, can be applied, to allow multiple conditions to be combined within the same grid. ### fieldFilter Attributes The `` 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 `` 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` | **๐Ÿ“Œ NOTE**\ 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 `` tag, which sets a filter to display only rows in which the "Bid" column contains a value greater than or equal to 1000. ```xml ... ... ``` ### Combining Filters with <and> and <or> Tags Filters defined using `` in the grid definition can be combined by placing multiple `` elements within `` and `` tags, like so: ```xml ... ... ``` 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: ```xml ``` 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.