Set Filter - Filter List
This section describes how Filter List values can be managed through custom sorting and formatting. Supplying filter values directly to the Set Filter is also discussed.
Sorting Filter Lists
Values inside a Set Filter will be sorted by default, where the values are converted to a string value and sorted in ascending order according to their UTF-16 codes.
When a different sort order is required, a Comparator can be supplied to the set filter as shown below:
The Comparator used by the Set Filter is only provided the values in the first two parameters, whereas the Comparator
for the Column Definition (
colDef) is also provided the row data as additional parameters. This is because when sorting rows,
row data exists. For example, take 100 rows split across the colour values
The column will be sorting 100 rows, however the filter will be only sorting two values.
If you are providing a Comparator that depends on the row data and you are using the Set Filter, be sure to provide the Set Filter with an alternative Comparator that doesn't depend on the row data.
The following example demonstrates sorting Set Filter values using a comparator. Note the following:
The Age (no Comparator) filter values are sorted using the default string order:
1, 10, 100...
The Age (with Comparator) filter has a custom Comparator supplied in the
filterParamsthat sorts the ages by numeric value:
1, 2, 3...
This section covers different ways to format the displayed Filter List values in the Set Filter.
A Value Formatter is a good choice when the string value displayed in the Filter List needs to be modified, for example adding country codes in parentheses after country name.
The following snippet shows how to provide a Value Formatter to the Set Filter:
In the code above, the same value formatter is supplied to the Column and Filter, however separate Value Formatters can be used.
The following example shows how Set Filter values are formatted using a Value Formatter. Note the following:
No Value Formatter does not have a Value Formatter supplied to the Set Filter. The column is supplied a
Value Formatter through
colDef.valueFormatter = countryValueFormatter.
With Value Formatter has the same Value Formatter supplied to the Column and Set Filter. The Set Filter is
supplied the value formatter through
filterParams.valueFormatter = countryValueFormatter.
- Click Print Filter Model with a filter applied and note the logged Filter Model (dev console) has not been modified.
A Cell Renderer is a good choice when the value displayed requires markup. For instance if a country flag image is to be shown alongside country names.
The same Cell Renderer can used to format the grid cells and filter values, or different renderers can be supplied to each. Note that the Cell Renderer will be supplied additional info when used to format cells inside the grid (as grid cells have row details that are not present for values inside a Filter List).
The following snippet shows how the Cell Renderers are configured:
The following example shows how Set Filter values are rendered using a Cell Renderer. Note the following:
No Cell Renderer does not have a Cell Renderer supplied to the Set Filter. The Column has a Cell Renderer
supplied to the Column using
colDef.cellRenderer = countryCellRenderer.
With Cell Renderer uses the same Cell Renderer to format the cells and filter values. The Set Filter is
supplied the Value Formatter using
filterParams.cellRenderer = countryCellRenderer.
- Click Print Filter Model with a filter applied and note the logged filter model (dev console) has not been modified.
Supplying Filter Values
The Set Filter will obtain the filter values from the row data by default. However it is also possible to provide values, either synchronously or asynchronously, for the Filter List.
The simplest approach is to supply a list of values to
filterParams.values as shown below:
Note that if there are missing values in the row data, the filter list will display all provided values. This could give users the impression that filtering is broken.
The following example demonstrates providing filter values using
filterParams.values. Note the following:
The Days (Values Not Provided) set filter obtains values from the row data to populate the filter list and as
'Sunday'are not present in the data they do not appear in the filter list.
- As the Days (Values Not Provided) filter values come from the row data they are sorted using a Custom Sort Comparator to ensure the days are ordered according to the week day.
The Days (Values Provided) set filter is given values using
filterParams.values. As all days are supplied the filter list also contains
As the Days (Values Provided) filter values are provided in the correct order, the default filter list
sorting is turned off using:
It is also possible to supply values asynchronously to the set filter. This is done by providing a callback function instead of a list of values as shown below:
Note in the snippet above the values callback receives a parameter object which contains
which allows values obtained asynchronously to be supplied to the set filter.
The interface for this parameter object is as follows:
The following example demonstrates loading set filter values asynchronously. Note the following:
filterParams.valuesis assigned a callback function that loads the filter values after a 3 second delay using the callback supplied in the params:
- Opening the set filter shows a loading message before the values are set. See the Localisation section for details on how to change this message.
- The callback is only invoked the first time the filter is opened. The next time the filter is opened the values are not loaded again.
By default, when values are passed to the set filter they are only loaded once when the set filter is initially
created. It may be desirable to refresh the values at a later point, for example to
reflect other filtering that has occurred in the grid. To achieve this, you can call
refreshFilterValues on the relevant filter that you would like to refresh. This will cause the values
used in the filter to be refreshed from the original source, whether that is by looking at the provided
values array again, or by re-executing the
values callback. For example, you might use
something like the following:
If you are using the grid as a source of values (i.e. you are not providing values yourself), calling this method will also refresh the filter values using values taken from the grid, but this should not be necessary as the values are automatically refreshed for you whenever any data changes in the grid.
If instead you want to refresh the values every time the Set Filter is opened, you can configure that using
When you refresh the values, any values that were selected in the filter that still exist in the new values will stay selected, but any other selected values will be discarded.
The following example demonstrates refreshing values. Note the following:
The Values Array column has values provided as an array. Clicking the buttons to change the values will update
the values in the array provided to the filter and call
refreshFilterValues()to immediately refresh the filter for the column.
The Values Callback column has values provided as a callback and is configured with
refreshValuesOnOpen = true. Clicking the buttons to change the values will update the values that will be returned the next time the callback is called. Note that the values are not updated until the next time the filter is opened.
If you select
'Elephant'and change the values, it will stay selected as it is present in both lists.
- If you select any of the other options, that selection will be lost when you change to different values.
- A filter is re-applied after values have been refreshed.
If there are missing / empty values in the row data of the grid, or missing values in the list of
Supplied Values, the Filter List will contain an entry called
which can be used to select / deselect all of these values. If this not the desired behaviour,
provide a Formatter to present blank values in a different way.
If you are providing complex objects as values, then you need to provide a Key Creator function (
to convert the objects to strings when using the Set Filter. Note the string is used to compare objects when
filtering and to render a label in the filter UI.
The snippet above shows a Key Creator function that returns the country name from the complex object. If the Key Creator was not provided on the Column Definition, the Set Filter would not work.
If the value returned by Key Creator is not human-readable then you should consider also providing a Formatter for the Filter List label.
The following example shows the Key Creator handling complex objects for the Set Filter. Note the following:
Country (Complex Object) column is supplied a complex object through
A Key Creator is supplied to the column using
colDef.keyCreator = countryKeyCreatorwhich extracts the
nameproperty for the Set Filter.
A value formatter is supplied to the column using
colDef.valueFormatter = countryValueFormatterwhich extracts the
nameproperty for the cell values.
Click Print Filter Model with a filter active and note the logged Filter Model (dev console) uses the
nameproperty from the complex object.
Multiple Values Per Cell
Sometimes you might wish to support multiple values in a single cell, for example when using tags. In this case, the Set Filter can extract each of the individual values from the cells, creating an entry in the Filter List for each individual value. Selecting a value will then show rows where any of the values in the cell match the selected value.
The example below demonstrates this in action. Note the following:
- The Animals (array) column uses an array in the data containing multiple values.
- The Animals (string) column uses a single string in the data to represent multiple values, with a Value Getter used to extract an array of values from the data.
- The Animals (objects) column retrieves values from an array of objects, using a Key Creator.
- For all scenarios, the Set Filter displays a list of all the individual, unique values present from the data.
- Selecting values in the Set Filter will show rows where the data for that row contains any of the selected values.
By default, when the Set Filter is created all values are selected. If you would prefer to invert this behaviour and have everything de-selected by default, you can use the following:
In this case, no filtering will occur until at least one value is selected.
The following example demonstrates different default states. Note the following:
- The Athlete column has everything selected when the Set Filter is first opened, which is the default
The Country column has nothing selected by default, as
defaultToNothingSelected = true
- When the Set Filter for the Country column is opened, the grid is not filtered until at least one value has been selected
Filter Value Tooltips
Set filter values that are too long to be displayed are truncated by default with ellipses. To allow users to see the full filter value, tooltips can be enabled as shown below:
The default tooltip component will be used unless a Custom Tooltip Component is provided.
The following example demonstrates tooltips in the Set Filter. Note the following:
- Filter values are automatically truncated with ellipses when the values are too long.
- Col A does not have Set Filter Tooltips enabled.
- Col B has Set Filter Tooltips enabled via
- Col C has Set Filter Tooltips enabled and is supplied a Custom Tooltip Component.
Continue to the next section: Data Updates.