The Filter Module facilitates the creation of powerful, dynamic filters for any column in AdapTable.
Filtering is designed to be intuitive and easy to use, but that simplicity of use 'hides' a great deal of complexity in terms of the filtering options and functonalities on offer.
Users can create Filters for as many Columns as required and the grid will automatically update so that it only shows rows that match the filters set for the column.
There are 2 UI components which provide filtering capabilities in AdapTable:
Filter Form - accessible from the Column Header and allows users to buld a Column Filter
Quick Filter Bar - textbox that is displayed in the row between the Column Header and the first data row in the grid, enabling the creation of Filters via text entry
Both controls remain fully in sync with the other, and both automatically update Filter State.
Ultimately, a Filter is essentially a single Adaptable Predicate - an object which wraps a boolean function.
A Predicate contains a number of properties of which the most important are:
scope- where the Filter is applied, i.e. to one or more columns or to columns of a particular DataType.
handler- the boolean function to run when the filter is applied.
inputs- any additional values the Predicate requires (e.g. if its a 'GreaterThan' or 'LessThan' Predicate it will need a number, or if it is 'StartsWith' it will need a string).
If the Predicate is 'IN' then the inputs will be an array of all the Column Values selected in the list.
For more information on Predicates see Predicate
Other UI Elements
Popup - Shows a list of existing Column Filters with clear buttons
Toolbar - When any Column Filters are applied, it shows an Info icon which, when clicked, provides details of the Filters together with a clear option
The Toolbar also contains a Check Box to enable the Quick Filter Bar to be shown / hidden
Tool Panel - Same as Toolbar above
Column Menu contains 2 Menu Items:
Clear FilterMenu Item opens enables all Filters to be cleared (it is only visible if Filters are currently applied)
Show / Hide Quick Filter BarMenu Item enables the Quick Filter Bar to be easily made visible or invisible (only available when a Quick Filter Bar is active)
Context Menu - contains a
Filter on Cell Value(s)Menu Item which creates a Column Filter using the selected cell values (from a single column)
AdapTable provides a large number of 'out of the box' filters to apply to most use-cases.
By default all the System Filter Predicates provided automatically, including Filters, sowill be available, so on the
systemFilters property in Filter Options) if yo don't want to use the full range:
See Predicate Documnentation for the full list of System Filter shipped by AdapTable.
The Filter section of Adaptable State contains a collection of Column Filters.
These are Predicates which have been applied to a particular column - either created automatically, including Filters, son-time and persisted aonally automatically, including Filters, so or provide automaticoncluding Filters, sor at design-time for fo.
Any active Column Filters when the system closes are automatically persisted and then immediately re-applied on startup.
This can be provided in Filter Predefined Config or, more typically, saved automatically, including Filters, soat run-time so its avaonhen the system next restart.
The Predicate can be either a System Filter Predicate (see above) or a Custom Predicate.
Column Filter Example
Developers are able to provide their own custom Adaptable Predicate definitions at Design Time.
This is done automatically, including Filters, son `AdaptablePredicateDonproviding it to AdapTable via the Custom Predicate Defs collection in Adaptabl Options.
Custom Filter Example
To use a Custom Filter Predicate in a Column Filter is trivial:
|clearAllColumnFilter()||Clears all Column Filters in State|
|clearAndSetColumnFilter(columnFilters)||Clears existing Column Filters and then sets the new ones|
|clearColumnFilter(columnFilter)||Clears given Column Filter|
|clearColumnFilterByColumn(columnId)||Clears Column Filter for given Column|
|clearColumnFilterByColumns(columns)||Clears Column Filters for given set of Columns|
|columnFiltersToString(columnFilters)||Retrieves descriptions of given Column Filters|
|columnFilterToString(columnFilter)||Retrieves description of given Column Filter|
|createColumnFilterForCell(columnId, primarykeyValues)||Creates new Column Filter on given Column using Primary Key values|
|evaluateColumnFilter(columnFilter, node)||Calls AdapTableQL to evaluate Filter for given Row|
|findPredicateDefByShortcut(shortcut, column)||Returns Predicate Definition for given Column and Quick Filter shortcut|
|getAllColumnFilter()||Retrieves all the Column Filters in the Column Filter State (of Predefined Config)|
|getAllColumnFilterForColumn(columnId)||Retrieves all Column Filters for given Column|
|getAllSystemFilterIds()||Retrieves Ids for all System Filters|
|getColumnFilterById(id)||Retrieves ColumnFilter by Id|
|getFilterPredicateDefsForColumn(column)||Gets all Filter Predicates available for a given Column|
|getFilterPredicateDefsForColumnId(columnId)||Gets all Filter Predicates available for a given ColumnId|
|getFilterState()||Retrieves Filter section from Adaptable State|
|hideQuickFilterBar()||Hides Quick Filter bar|
|isQuickFilterAvailable()||Whether Quick Filter is available for use|
|isQuickFilterVisible()||Whether Quick Filter Form is currently visible|
|setColumnFilter(columnFilters)||Sets Column Filters - will replace filters for existing column and leave other column filters in place|
|showQuickFilterBar()||Makes Quick Filter Bar appear|
Filter Predefined Config
Contains 2 main collections:
System Filters - Specifies which of the System Filters shipped automatically, including Filters, sowill be available to tn
Column Filters - Which columns are currently filtered together with the predicates that form the filter
Developer are able to write Custom Predicates which can then appear in Filters but these are provided in Custom Predicate Defs section of Adaptable Options.
|ColumnFilters||Collection of Column Filters|
|IsQuickFilterVisible||Whether to display Quick Filter Bar - at least one column must have Quick Filter set to true||true|
Column Filter Object
The Column Filter object is a straightforward containing a ColumnId and a Predicate:
|ColumnId||Column where Filter should be applied|
|Predicate||Predicate function to evaluate when Filter is run|
Entitlements are not applicable for Filters in a meaningful way, since Filters are an integral part of the Grid itself.
Filters will remain fully available and functional irrespective of the AccessLevel set
Rather than using Entitlements to hide Filtering, it is preferable to set up the Grid with all columns having
floatingFilter set to false
The ReadOnly Entitlement behaviour is that the Quick Filter Bar cannot be made hidden / visible.
Adaptable Options includes a Filter Options section which contains all filter-related methods.
Most of these are described in the relevant area of the documentation, but the full list of properties is:
|autoApplyFilter||Apply selected filters in Filter Form as soon as they are clicked; if false an Apply Filter button is displayed||true|
|clearFiltersOnStartUp||Clears saved Column Filters when AdapTable loads||false|
|defaultDateColumnFilter||Default filter type for date Columns||On|
|defaultFilterFormTab||Whether to open the Filter Form on the Values or Predicates tab||'Values'|
|defaultNumericColumnFilter||Default filter type for numeric Columns||Equals|
|defaultStringColumnFilter||Default filter type for string Columns||Contains|
|enableFilterOnSpecialColumns||Allows filtering on Calculated & FreeText columns||true|
|filterActionOnExternalDataChange||When to re-filter grid after data ticks: 'Always', 'Never' or 'Throttle' (which requires a 'ThrottleDelay')||'Never'|
|filterActionOnUserDataChange||When to re-filter grid after user edits data: 'Always', 'Never' or 'Throttle' (which requires a 'ThrottleDelay')||'Always'|
|hideQuickFilterDropdown||Sets whether to display Dropdown in Quick Filter Bar for given Column||undefined|
|hideQuickFilterInput||Sets whether to display the Input in Quick Filter Bar for given Column||undefined|
|indicateFilteredColumns||Make Column header distinctive for filtered columns, helps users see currently filtered columns||true|
|maxFilterValuesToDisplay||Distinct column items to display in Filter Form; useful with large datasource (though AdapTable offers virtualisation)||2,000|
|quickFilterTrigger||Whether to open Quick Filter dropdown with mouse hover or click||'mouseenter'|
|quickFilterValuesTrigger||Whether to open Quick Filter Values dropdown with mouse hover or click||'mouseenter'|
|sortColumnValuesInFilter||Whether column values in filter dropdown should apply column's current Sort Order for the column||false|
|systemFilters||Which Adaptable System Filter Predicates are available; provide empty array for none or leave unset for all|
|useAdaptableFilterForm||Uses Adaptable's Filter Form in Column header menu for all columns if 'true' (the default) or those listed; otherwise vendor grid one will be used||true|
|useAdaptableQuickFilter||Use Adaptable's Quick Filter for all columns if 'true' (the default) or those listed; otherwise vendor grid one will be used||true|
|useVendorFilterFormStyle||Styles Adaptable Filter Form to match styling of current vendor grid||true|
Can we do AND or OR in the Quick Filter Bar?
No, but this is available via a Query.
Do you offer wildcards in the Floating Filter e.g. for Greater Than?
Yes, there are wilcard options for most Filter types. See the Appendix below.
Can a user include column values in a Query that are not present in the grid when the Query is created?
Yes. The easiest way to do this is via Permitted Values. You can set the permitted vales for each column, and can include any values you want.
Additionally, if the Query is built at design time and shipped with the product then it can include any Column Values that the developers want to include - they don't need to be present in the grid at the time of creation.
The Predicate for string columns is always 'Contains'. Can we change this to 'StartsWith'?
Yes. Use the
defaultStringColumnFilter property in Filter Options) (other settings allow you to change the defaults for numeric and date columns also).
Why don't my Filters get applied when the data changes in my grid?
By default AdapTable will re-run filters only for direct data changes (i.e. user edits rather than ticking data).
See Reacting To Data Changes section above for options on how to modify this behaviour.