Grid Filter

Managing the Grid Filter

View as Markdown

Summary

  • Developers can define a Grid Filter in a Layout and also configure how Grid Filters are used
  • Run-time users can create and manage the Grid Filter in multiple ways

Defining

The Grid Filter in AdapTable is defined inside the Layout object

Caution

This means that the Grid Filter is per-Layout only

The Grid Filter can be defined for both Table and Pivot Layouts.

Developer Guide

Adding Grid Filter to Layout

const initialState: InitialState = {
  Layout: {
    CurrentLayout: 'Table Layout',
    Layouts: [
      {
        Name: 'Table Layout',
        TableColumns: ['currency', 'orderDate', 'github_watchers', 'price'],
        GridFilter: {
          Expression: '[currency]="EUR" OR [price] > 5000',
        },
      },
      {
        Name: 'Pivot Layout',
        PivotColumns: ['language'],
        PivotGroupedColumns: ['license'],
        PivotAggregationColumns: [{ ColumnId: 'price', AggFunc: 'sum' }],
        GridFilter: {
          Expression: '[currency]="EUR" OR [price] > 5000',
        },
      },
    ],
  },
};
1
Add Grid Filter to the Layout Definition

Add the GridFilter prop to the Layout in order to filter across the whole Grid.

Add it separately to each Layout where you want to apply it.

The Grid Filter can be defined for both Table and Pivot Layouts.

2
Provide the Expression

The Grid Filter contains an Expression property.

This is a simple (Boolean) Expression that is evaluated by AdapTableQL.

Run-time users (if correctly permissioned) can write, edit, delete, clear, save, suspend and reload Grid Filter Expressions.

Creating

AdapTable provides two UI components to facilitate the creation of the Grid Filter Expression at run-time:

These editors open in the Settings Panel when the user clicks Expand (or the expression summary) in the Grid Filter Toolbar or Tool Panel.

Use Apply Grid Filter button in the Settings Panel to apply the draft Expression and close the panel.

Clear, Save, Suspend and Named Query actions remain on the Toolbar / Tool Panel.

Note

  • Once created, the Expression is shown as a summary in the Toolbar (it is not edited in place)
  • The Grid Filter Toolbar works especially well when Pinned above the Grid

Users can create multiple Grid Filters and load them on demand, but only one Grid Filter can be run (and active) at any one time.

Hint

Editing a Named Query creates a new Grid Filter - which can then itself be saved as a new Named Query

Validating

AdapTableQL automatically validates the Grid Filter as it is being written.

Caution

AdapTable will only enable Apply Grid Filter if the Grid Filter's Expression is valid

If an applied Grid Filter becomes invalid, the Toolbar / Tool Panel shows an Invalid indicator next to the expression summary.

Set performExpressionValidation in Expression Options to false to turn off automatic validation.

Hint

This is useful if you are evaluating the Grid Filter on your server

Clearing

The Grid Filter can be cleared by clicking the Clear Grid Filter button in the Grid Filter Toolbar or Tool Panel.

This will have the effect of showing all rows in the Grid (subject to any Column Filters that have been applied).

Hint

  • Cleared Queries can be subsequently reloaded
  • This applies both to Named Queries or unsaved Grid Filters (but only those created in the current session).

Saving

A Grid Filter can be saved by clicking the Save button in the Grid Filter Toolbar or Tool Panel.

This will save the Grid Filter as a Named Query for re-use as required.

Caution

Grid Filters which are not saved explicitly are still persisted temporarily and can be reloaded during the current session

Loading

The Grid Filter Toolbar and Tool Panel both contain a control which allows previously run Expressions to be loaded and then run as a Grid Filter.

This includes all saved Named Queries, plus any unsaved Grid Filters created in the Current Session (listed as Recent Grid Filters).

Note

Unsaved Grid Filters are named according to the time of creation (e.g. 'Grid Filter at 5:38:33 PM')

Suspending

An active Grid Filter can be suspended from the Toolbar or Tool Panel without clearing it.

While suspended:

  • the Expression remains visible (muted) in the summary
  • it is no longer applied to the Grid
  • editing is blocked until the Filter is unsuspended

Use Unsuspend to re-apply the same Expression.

Configuring

Setting Editors

Grid Filter uses the same Expression editors as the rest of AdapTable — the Query Builder and Expression Editor.

Which of those are offered, and which opens first, is configured once for all Boolean Expressions via 2 properties in expressionOptions.editorOptions:

  • availableEditors - sets which of the 2 Editors are available for users
  • defaultEditor - which Editor is displayed by default (can be configured on a per-Module basis)

Find Out More

See Managing Expression Components for full details and demos

Clearing on Startup

AdapTable always saves the previously applied Grid Filter into Adaptable State (via the Current Layout).

It will then automatically re-apply this Grid Filter when the Application is reloaded.

If this behaviour is not desired, set the clearFiltersOnStartUp property in Filter Options to true.

clearFiltersOnStartUp

Default: false
boolean
Clear the Grid Filter (and any Column Filters) applied in previous session when Application re-starts
PreviousGrid Filter