Filters Module

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.

note

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.

Filter Components

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

important

Both controls remain fully in sync with the other, and both automatically update Filter State.

Predicate

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).

    tip

    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

In addition to the Filter Form and Quick Filter Bar (dealt with in separate topics), the Filter Module also includes the following 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

    note

    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 Filter Menu Item opens enables all Filters to be cleared (it is only visible if Filters are currently applied)
    • Show / Hide Quick Filter Bar Menu 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)

System Filters

AdapTable provides a large number of 'out of the box' filters to apply to most use-cases.

tip

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:

export default {
filterOptions = {
systemFilters: ['Positive', 'Today', 'Blanks'],
};

See Predicate Documnentation for the full list of System Filter shipped by AdapTable.

Column Filters

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.

important

Any active Column Filters when the system closes are automatically persisted and then immediately re-applied on startup.

note

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

// Create 3 column Filters using the following predicates:
// Values ('Employee' column) which is basically an 'IN' predicate
// Between ('InovicedCost' column) which takes 2 numeric inputs
// InPast ('OrderData' column) which requires no inputs
Filter: {
ColumnFilters: [
{
ColumnId: 'Employee',
Predicate: {
PredicateId: 'Values',
Inputs: ['Janet Leverling', 'Margaret Peacock', 'Nancy Davolio'],
},
},
{
ColumnId: 'InvoicedCost',
Predicate: {
PredicateId: 'Between',
Inputs: [10, 300],
},
},
{
ColumnId: 'OrderDate',
Predicate: {
PredicateId: 'InPast',
},
},
],
},

Custom Filters

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:

Filter: {
ColumnFilters: [
{
ColumnId: 'Employee',
Predicate: { PredicateId: 'new_starter' },
},
{
ColumnId: 'LastUpdatedTime',
Predicate: { PredicateId: 'after_work' },
},
],
},
const adaptableOptions: AdaptableOptions = {
customPredicateDefs: [
{
id: 'new_starter',
label: 'New Starter',
columnScope: { ColumnIds: ['Employee'] },
moduleScope: ['filter'],
handler(params: PredicateDefHandlerParams) {
return (
params.value == 'Robert King' ||
params.value == 'Laura Callahan' ||
params.value == 'Andrew Fuller'
);
},
},
{
id: 'after_work',
label: 'After Work',
columnScope: { ColumnIds: ['LastUpdatedTime'] },
moduleScope: ['filter'],
handler(params: PredicateDefHandlerParams) {
return (params.value as Date).getHours() > 17;
},
},
],
};

Filter API

MethodDescription
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

tip

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.

PropertyDescriptionDefault
ColumnFiltersCollection of Column Filters
IsQuickFilterVisibleWhether to display Quick Filter Bar - at least one column must have Quick Filter set to truetrue

Column Filter Object

The Column Filter object is a straightforward containing a ColumnId and a Predicate:

PropertyDescription
ColumnIdColumn where Filter should be applied
PredicatePredicate function to evaluate when Filter is run

UI Entitlements

Entitlements are not applicable for Filters in a meaningful way, since Filters are an integral part of the Grid itself.

caution

Filters will remain fully available and functional irrespective of the AccessLevel set

tip

Rather than using Entitlements to hide Filtering, it is preferable to set up the Grid with all columns having filterable and floatingFilter set to false

The ReadOnly Entitlement behaviour is that the Quick Filter Bar cannot be made hidden / visible.

Filter Options

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:

PropertyDescriptionDefault
autoApplyFilterApply selected filters in Filter Form as soon as they are clicked; if false an Apply Filter button is displayedtrue
clearFiltersOnStartUpClears saved Column Filters when AdapTable loadsfalse
defaultDateColumnFilterDefault filter type for date ColumnsOn
defaultFilterFormTabWhether to open the Filter Form on the Values or Predicates tab'Values'
defaultNumericColumnFilterDefault filter type for numeric ColumnsEquals
defaultStringColumnFilterDefault filter type for string ColumnsContains
enableFilterOnSpecialColumnsAllows filtering on Calculated & FreeText columnstrue
filterActionOnExternalDataChangeWhen to re-filter grid after data ticks: 'Always', 'Never' or 'Throttle' (which requires a 'ThrottleDelay')'Never'
filterActionOnUserDataChangeWhen to re-filter grid after user edits data: 'Always', 'Never' or 'Throttle' (which requires a 'ThrottleDelay')'Always'
hideQuickFilterDropdownSets whether to display Dropdown in Quick Filter Bar for given Columnundefined
hideQuickFilterInputSets whether to display the Input in Quick Filter Bar for given Columnundefined
indicateFilteredColumnsMake Column header distinctive for filtered columns, helps users see currently filtered columnstrue
maxFilterValuesToDisplayDistinct column items to display in Filter Form; useful with large datasource (though AdapTable offers virtualisation)2,000
quickFilterTriggerWhether to open Quick Filter dropdown with mouse hover or click'mouseenter'
quickFilterValuesTriggerWhether to open Quick Filter Values dropdown with mouse hover or click'mouseenter'
sortColumnValuesInFilterWhether column values in filter dropdown should apply column's current Sort Order for the columnfalse
systemFiltersWhich Adaptable System Filter Predicates are available; provide empty array for none or leave unset for all
useAdaptableFilterFormUses Adaptable's Filter Form in Column header menu for all columns if 'true' (the default) or those listed; otherwise vendor grid one will be usedtrue
useAdaptableQuickFilterUse Adaptable's Quick Filter for all columns if 'true' (the default) or those listed; otherwise vendor grid one will be usedtrue
useVendorFilterFormStyleStyles Adaptable Filter Form to match styling of current vendor gridtrue

FAQ

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.

More Information