1. Filtering rows
Showing only rows that satisfy selected criteria
-
TreeGrid provides three independent ways of filtering rows. All of them can be applied at the same time.
-
Basic filters done by <Filter> row. There can be more <Filter> rows in one grid.
The <Filter> row supports simple filter for every column like in MS Excel.
-
Advanced filters done by Cfg Search... attributes and editable in <Search> row.
It lets users to write their complex expression to filter by or just string to search in all or specified columns.
It is described and more demonstrated in next tutorial example 03-Search_and_advanced_filters.html.
-
Custom filters done by API method SetFilter or FilterDateRange / FilterTextRange.
There can be set more independent filters identified by name.
It can be used for example to switch data parts by tabs, combos or radio buttons.
-
Filter permitions
-
A Cfg attribute
Filtering
='0' completely disables filtering in grid.
It affects all filters (basic, advanced, custom).
-
A Cfg attribute
Filtered
='0' temporary disables filtering in grid.
This attribute value can be changed by actions FilterOff and FilterOn.
It affects only basic filter (for search there is similar attribute Searched and actions SearchOff and SearchOn).
-
A row can have set
CanFilter
='0' to restrict filtering (hiding) this rows by any filter.
In tree it can be set also to '2' to hide the row if all its children are hidden. See next example 02-Filtering_in_tree.html.
It affects all filters (basic, advanced, custom).
-
A column can have set
CanFilter
='0' to not filter by this column.
It affects only basic filter (for search there is similar attribute CanSearch).
-
A column can have set
CanFilter
='2' to test all its cell attributes CanFilter, if the cell attribute is set to 0,
the row is not filtered by this column.
It affects only basic filter and custom filter with column parameter set (for search there is no similar setting).
Cell value for filtering
Every cell can have set special value by FilterValue
to use it for filtering instead of the cell value.
The value can be also dynamically created by JavaScript in API event OnGetFilterValue.
It affects basic and advanced filters and custom filters set by FilterTextRange / FilterDateRange, but not by SetFilter
-
API events
Before filtering start it is called OnFilter API event. It can return true to provide own filtering and not the default one.
After filtering finishes, it is called OnFilterFinish API event.
For every row it is called OnRowFilter event to let you change the result of the filtering row.
The grid can be re-filtered after some external change by DoFilter method.
All these events are called for all filters (basic, advanced, custom).
-
Simple filter (<Filter>)
Simple filter is done by fixed <Filter> row(s) placed into <Head> or <Foot> section.
-
Filtering strings
There are four attributes used also for sorting and grouping. To set the option only for filter, set it to <Filter> cell.
-
Column / Filter cell attribute
CaseSensitive
to compare the strings case sensitive. By default is on.
-
Column / Filter cell attribute
LocalCompare
to compare the strings according to browser's locale settings.
It has sense especially for case insensitive comparing. By default is off.
-
Column / Filter cell attribute
WhiteChars
as list of characters to ignored when comparing. The strings are compared after these values are removed from them.
-
Column / Filter cell attribute
CharCodes
as list of character pairs to replace the first character by the second one in all strings before comparing them. Useful for example to compare strings without punctuation in many languages.
-
User interface (<Filter> row)
-
The actual or predefined filter values are in cell values of the <Filter> row.
-
The actual or predefined operator is set by cell attribute
Filter
. It can be:
Off: 0 - Off
Number filter: 1 - Equal, 2 - Not equal, 3 - Less than, 4 - Less than or equal, 5 - Greater than, 6 - Greater than or equal
String filter: 7 - Begins with, 8 - Does not begin with, 9 - Ends with, 10 - Does not end with, 11 - Contains, 12 - Does not contain
-
Every filter cell shows left icon to popup filter menu to select filter operator.
The menu can be hidden by cell attribute ShowMenu='0'. For Enum type is the menu hidden by default, it can be shown by ShowMenu='1'.
The individual menu items (visibility and order) can be set by MenuItems cell attribute.
The menu can be shown also by calling action ShowFilterMenu.
-
After the filter cell value is edited or changed by a user and the filter operator is 0 (off), the operator can be automatically set to DefaultFilter cell attribute value.
By default it is 1 for number types and 11 for string types.
-
When a user inputs or selects value set by attribute FilterOff, the filter operator is automatically changed to 0 (off). It is empty string by default.
For Enum type it can be also value not existing in Enum array to add it to disable the filter.
-
Enum type can filter by the Enum strings or by EnumKeys values when set cell attribute FilterEnumKeys='1', useful especially when it filters different type cells with FilterValue set.
-
To choose more values to filter by, set
Range
='1' for the Filter cell. Especially for Enum type or Button Defaults.
-
All the cell values and operator values can be changed by API method ChangeFilter.
-
Advanced filter (Search)
done by Cfg Search... attributes and editable in <Search> row.
It lets users to write their complex expression to filter by or just string to search in all or specified columns.
It is described and more demonstrated in next tutorial example 03-Search_and_advanced_filters.html.
-
Custom filters
It is possible to set custom filters by API. These filters are identified by their names and are independent on each other and on the basic and advanced filters.
In this example are demonstrated in top tabs to choose specific part of the data to display.
-
There are two special API methods FilterDateRange and FilterTextRange to filter rows with values in given column in given range.
-
All other custom filters can be set by API method
SetFilter
. It accepts any JavaScript code like in grid Formula to apply it for every iterated row.
-
Calling SetFilter without filter parameter clears the given filter set by any or these three methods.