AdapTable Version:

Framework:

Custom Predicates

Summary

In addition to the many Predicates shipped by AdapTable, developers can provide their own Predicate Definition
This is done via the customPredicateDefs property in Predicate Options
Once created, Custom Predicates are used in exactly the same way as System Predicates
Each Predicate Definition must:
- include a handler function to be invoked by AdapTable
- configure which Modules can use the Predicate
- set which Columns (or DataTypes) can access the Predicate
Custom Predicates can override existing System Predicates with bespoke behaviour

The Predicates shipped by AdapTable can be extended by Custom Predicates provided by developers.

Custom Predicate Definitions

Custom Predicates are provided in the customPredicateDefs property in Predicate Options.

Each is based on a Predicate Definition object.

Caution

Custom Predicates add bespoke items to the Predicates available in AdapTable
Use Custom Expression Functions to extend Expressions

customPredicateDefs

AdaptablePredicateDef

Definitions for Custom-provided Predicates

AdaptablePredicateDef

Custom Predicate Definitions are provided by developers at Design-Time.

These extend the many Predicates shipped by AdapTable.

The full definition of the Predicate Definition is as follows:

Property	Description
columnScope	Columns (or DataTypes) where Predicate is active
handler	Actual boolean function invoked when evaluating the Predicate
icon	Icon to show (primarily used in Filter dropdown)
id	Predicate Id
inputs	Inputs the Predicate can take
label	Name of the Predicate
moduleScope	Modules where Predicate can run
shortcuts	Keyboard shortcuts to initiate predicate - used in Quick Filter bar
toString	String representation of the Predicate

Mandatory Properties

The Predicate Definition object contains many properties which can be set, of which 5 are mandatory:

id

The id defines how the Predicate is referenced in other objects (e.g. Column Filters)

label

The label is the name given to the Predicate and how it will be referenced in the AdapTable UI.

Hint

The id is the unique identifier for the Predicate
The label is a more friendly way of identifying the Predicate in the UI

handler

The handler property is a function which is invoked by AdapTable each time the predicate is evaluated.

The function receives information about the current evaluation context and returns a boolean (true / false).

Deep Dive

Understanding the handler property

The handler function is defined as follows:

handler: (context: PredicateDefHandlerContext) => boolean;

As can be seen, it receives a PredicateDefHandlerContext object and returns a boolean.

The context contains all the properties required for predicate evaluation (e.g. given cell, node and column).

The full definition is as follows:

Property	Description
column	AdapTable Column which contains the cell
displayValue	Display value in cell being evaluated
groupValues	For grouped columns, the array with all the values starting from the root group to the current node
inputs	Any (optional) inputs required to perform evaluation
node	AG Grid Row node which contains the cell
oldValue	Previous value in cell (e.g. if evaluating an edit)
predicatesOperator	Logic used when combining multiple Predicates ('AND'\|'OR')
rawValue	Raw value in cell being evaluated (as per underlying data source)
treeSelectionState	Optional TreeSelectionState - used for `In` predicate, when evaluating the grouped column. If this is not provided, another valid implementation is used.
value	Value in cell being evaluated (normalized as per Column DataType)
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

moduleScope

This array property specifies which AdapTable Modules can use the Predicate.

The moduleScope property is of type PredicateModuleScope which can be one, some, or all of:

customFilter - used in Column Filters
alert - can trigger an Alert
flashingCell - available in Flashing Cells
formatColumn - used to define a Format Column
badgeStyle - used to define a Badge Style

columnScope

The columnScope property - of type Column Scope - defines where the Predicate can be applied.

Note

For System Predicates the Scope is always of type DataType
For Custom Predicates the Scope can be a DataType, but can also be limited to particular ColumnId(s)

Find Out More

See the Guide to Scope in AdapTable for more information

Creating Custom Predicates

Now lets put this all together see how to create a Custom Predicate Definition.

Developer Guide

Creating a Custom Predicate Definition

In this guide we will create a Custom Predicate Definition that will check whether a given date is after a fictitious takeover date.

const adaptableOptions: AdaptableOptions = {
  predicateOptions:{
    customPredicateDefs: [
      {
        id: 'post_takeover',
        label: 'Post Takeover',
        columnScope: {DataTypes: ['date']},
        moduleScope: ['columnFilter', 'alert', 'flashingcell', 'formatColumn'],
        handler(context: PredicateDefHandlerContext) {
          return (context.value as Date) > new Date('2019-09-21');
        },
        toString: () => `> '2019-09-21'`,
      },
    ],
  },
};

Provide an Id and Label

Supply 2 properties to identify the Custom Predicate:

id - the unique identifier for the Predicate
label - how the Predicate will be referenced in the UI

Note

Both these properties are mandatory

const adaptableOptions: AdaptableOptions = {
   predicateOptions:{
    customPredicateDefs: [
      {
        id: 'post_takeover',
        label: 'Post Takeover',
        columnScope: {DataTypes: ['date']},
        moduleScope: ['columnFilter', 'alert', 'flashingcell', 'formatColumn'],
        handler(context: PredicateDefHandlerContext) {
          return (context.value as Date) > new Date('2019-09-21');
        },
        toString: () => `> '2019-09-21'`,
      },
    ],
  },
};

Specify the Column Scope

The columnScope property defines where the Predicate can be applied.

It is of type Column Scope used in many places in AdapTable.

You can provide either:

an array of ColumnIds
an array of DataTypes (though its likely only one value will be used)

const adaptableOptions: AdaptableOptions = {
     predicateOptions:{
      customPredicateDefs: [
        {
          id: 'post_takeover',
          label: 'Post Takeover',
          columnScope: {DataTypes: ['date']},
          moduleScope: ['columnFilter', 'alert', 'flashingcell', 'formatColumn'],
          handler(context: PredicateDefHandlerContext) {
            return (context.value as Date) > new Date('2019-09-21');
          },
          toString: ({inputs}) => `> ${inputs[0]}`,
        },
      ],    
};

Specify the Module Scope

The moduleScope property defines which Modules in AdapTable can use the Custom Predicate. The value will be one, some, or all of

columnFilter - using the Column Filters
alert - see Alerts
flashingcell - see Flashing Cells
formatcolumn - see Column Formatting
badgeStyle - see Badge Styles

const adaptableOptions: AdaptableOptions = {
     predicateOptions:{
       customPredicateDefs: [
        {
          id: 'post_takeover',
          label: 'Post Takeover',
          columnScope: {DataTypes: ['date']},
          moduleScope: ['columnFilter', 'alert', 'flashingcell', 'formatColumn'],
          handler(context: PredicateDefHandlerContext) {
            return (context.value as Date) > new Date('2019-09-21');
          },
          toString: () => `> '2019-09-21'`,
        },
      ],
  },
};

Provide a Handler function

The handler function will be invoked by AdapTable each time the predicate is evaluated.

This is a mandatory property.

handler receives a PredicateDefHandlerContext object (that contains all the arguments required for evaluation) and returns a boolean.

const adaptableOptions: AdaptableOptions = {
     predicateOptions:{
      customPredicateDefs: [
      {
        id: 'post_takeover',
        label: 'Post Takeover',
        columnScope: { DataTypes: ['date'] },
        moduleScope: ['columnFilter', 'alert', 'flashingcell', 'formatColumn'],
        handler(context: PredicateDefHandlerContext) {
          return (context.value as Date) > new Date('2019-09-21');;
        },
        toString: () => `> '2019-09-21'`,
      }],
  };
}

Supply a toString() implementation

The toString property is a function which defines how AdapTable will describe the predicate in the UI Settings Screen.

It should be succint but as descriptive as required.

It can take an input if required (see step below).

const adaptableOptions: AdaptableOptions = {
    predicateOptions: {
      customPredicateDefs: [
        {
          id: 'long_string',
          label: 'Long String',
          columnScope: {DataTypes: ['text']},
          moduleScope: ['formatcolumn'],
          handler(context: PredicateDefHandlerContext) {
            return (context.value as String).length > context.inputs[0];
          },
          inputs: [{type: 'number'}],
          toString: ({inputs}) => `cell length > ${inputs[0]}`,
        },
      ],
  },
};

Provide any Inputs (if required)

It is possible that the Custom Predicate might require an input.

When this is the case AdapTable will supply the appropriate editor in the UI (in this case in the Format Column wizard).

Here we have provided a Custom Predicate that works on string columns and is triggered when the cell length is greater than the inputted number.

Note: we have provided this input value to the toString() method.

Custom Predicates

Fork Fork

This demo creates 3 Custom Predicate Definitions, with a variety of different Module and Column Scope:
- Popular (Module Scope of columnFilter; Column Scope of name) - where the Row has many Stars and Watchers
- Vanilla (Module Scope of columnFilter & formatColumn; Column Scope of language) - where language is JavaScript or HTML
- Popular (Module Scope of columnFilter & alert; Column Scope of date Columns) - where Date > 19 Dec 2021
We have demonstrated some of these Predicates in Action by:
- Setting a Column Filter to the Name Column using the Popular Predicate
- Provided a Conditional Style for the Language Column that uses the Vanilla Predicate
- Created a Warning Alert for Date Columns that use the Recent Predicate

Try It Out

Edit a date to be after 19 Dec 2021 and see the Alert appear

import {
  AdaptableOptions,
  PredicateDefHandlerContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Predicates',
  predicateOptions: {
    customPredicateDefs: [
      {
        id: 'big_github',
        label: 'Popular',
        columnScope: {
          ColumnIds: ['name'],
        },
        moduleScope: ['columnFilter'],
        handler(params: PredicateDefHandlerContext) {
          const githubStarsCount: number = params.node.data.github_stars;
          const watchersCount: number = params.node.data.github_watchers;
          return githubStarsCount > 50000 && watchersCount > 500 ? true : false;
        },
      },
      {
        id: 'vanilla',
        label: 'Vanilla',
        columnScope: {
          ColumnIds: ['language'],
        },
        moduleScope: ['columnFilter', 'formatColumn'],
        handler(params: PredicateDefHandlerContext) {
          return params.value == 'JavaScript' || params.value == 'HTML';
        },
      },
      {
        id: 'recently_updated',
        label: 'Recent',
        columnScope: {
          DataTypes: ['date'],
        },
        moduleScope: ['columnFilter', 'alert'],
        handler(params: PredicateDefHandlerContext) {
          const recentDate = new Date('2021-12-19');
          return (params.value as Date) > recentDate;
        },
      },
    ],
  },

  initialState: {
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'language-vanilla',
          Style: {
            BackColor: '#87cefa',
            ForeColor: 'Black',
          },
          Scope: {
            ColumnIds: ['language'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'vanilla',
              },
            ],
          },
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['ColumnFilter'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-recently-updated',
          Scope: {
            DataTypes: ['date'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'recently_updated',
              },
            ],
          },
          AlertProperties: {
            DisplayNotification: true,
          },
          MessageType: 'Warning',
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'description',
            'open_issues_count',
            'created_at',
            'license',
          ],
          ColumnFilters: [
            {
              ColumnId: 'name',
              Predicates: [{PredicateId: 'big_github'}],
            },
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Adding Inputs

Some Custom Predicates might require an additional input value in order to perform the evaluation.

Hint

Many System Predicates require inputs from users
For instance GreaterThan compares the input value against base value and returns true if the latter is larger

The inputs property is an array of any type.

The reason it is an arrray is because while most inputs are a single value, some require 2 inputs (e.g. Between)

Note

2 System Predicates - In and NotIn - can take an array of unlimited length

AdapTable will display an appropriate UI input for each value provided.

Custom Predicates with Inputs

Fork Fork

This demo creates a Custom Predicate Definition Long String which also receive an input
It has moduleScope of formatColumn and columnFilter and a columnScope of String columns.
It receives an input (of type number) which is used to verify whether the string is "big" (or not)
We have created a Format Column on the Description with an input of 50 - so entries more than 50 characters are coloured

Try It Out

Create a new Column Filter on the Lanague Column using the Long String Custom Predicate and an input of 5
Note that the 2 rows with HTML will be filtered out

Extending System Predicates

In addition to providing entire new Custom Predicates, developers can provide Custom Predicates which extend the System Predicates shipped by AdapTable.

This is done by using the extends property in the Predicate Definition which takes the PredicateId to override.

Extending System Predicates can be done in 2 ways depending on the behaviour required:

Replacing the System Predicate - to do this provide the same Id as the Predicate being extended
Adding alongside System Predicate - to do this provide a different Id to the Predicate being extended

Custom Predicates overriding System Predicates Behaviour

Fork Fork

This example overrides 5 System Date Predicates with Custom Predicates that have Timezone support: Today, Yesterday, Tomorrow, InPast, InFuture
We only override the handler for each of the System Predicates, and do not change any other properties
However for Today we provide a different Id of Now - which means that both Today and Now appear in the dropdown (the latter at the bottom)
The demo displays a list of tasks with due dates, which are all UTC dates, filtered according to the local time of the selected Timezone
Note: The Timezone support (implemented using the Luxon library) is provided only for demonstration purposes and is not production ready!
We use a local ZonedDateTimeService which is provided in Adaptable Context, making it available in all AdapTable's callbacks
We also leverage the systemFilterPredicates property to remove other Date Predicates whose default implementation is not timezone compatible

Try It Out

Change the Timezone via the TimezoneSelect component in the custom toolbar and/or the Due Date filter and observe the results

In the example above, we overrode the handler property in order to provide a new implementation for some System Predicates.

But any property in a System Predicate can be overridden; the behaviour is as follows:

Properties provided in the Custom Predicate will replace their equivalents in the System Predicate
Properties not expressly provided in the Custom Predicate will use that provided by the System Predicate

Hint

This allows you just to provide a new label, or icon for the Predicate and leave the implementation untouched

Custom Predicates overriding System Predicates Props

Fork Fork

In this example we extend 4 System Predicates by providing properties other than handler:
- LessThan and GreaterThan have new labels of "Fewer" and "More" respectively
- Contains and NotContains have been given different icons

PreviousSystem Predicates NextTechnical Reference

Framework: