Custom Expression Function Scope

Summary

Custom Expression Functions may be provided only to specific Adaptable Modules

By default every Custom Expression Function created is available in all Modules in AdapTable.

However sometimes developers might wish to limit this, and allow the Custom Expression Function to be used in some Modules but not others.

This is possible by using the moduleExpressionFunctions section in Expression Options.

Developer Guide

Creating Custom Expression Functions for specific Adaptable Modules

In this Guide we will create the same 2 Custom Expression Functions as in the Step by Step Guides above but limit where they can be applied:

the Custom Boolean Expression Function will be available only in the Alert Module
the Custom Scalar Expression Function will be available only in the CalculatedColumn Module

// Expression Options
expressionOptions: {
  moduleExpressionFunctions: {
    Alert: {
      customBooleanFunctions: {
        THIS_BUSINESS_YEAR: {
          handler(args: any[], context: ExpressionContext) {
              const startBusinessYear = new Date(2023, 4, 1);
              return new Date(args[0]) > startBusinessYear;
            },
            returnType: 'boolean',
            description: 'Returns true if Date is in current Business year',
            signatures: ['THIS_BUSINESS_YEAR(dateToCheck: Date)'],
            examples: ['THIS_BUSINESS_YEAR([tradeDate])'],
        }
      }
    },
    CalculatedColumn: {
      customScalarFunctions: {
        USD_CONVERT: {
          handler(args, context: ExpressionContext) {
            const inputValue: number = args[0];
            if (isNaN(inputValue)) {
              return undefined;
            }
            const oldCurrency = args[1];
            if (oldCurrency === 'USD') {
              return inputValue;
            }

            if (oldCurrency === 'EUR') {
              return inputValue * 1.15;
            } else if (oldCurrency === 'GBP') {
              return inputValue * 1.2;
            }
            return undefined;
          },
          description: 'Converts EUR & GBP Currencies to Dollar',
          signatures: ['USD_CONVERT(val: number, ccy: string)'], 
          examples: [
            'USD_CONVERT([value],[currency])',
            'USD_CONVERT([value], "GBP")',
          ],
        }
      }
    }
  }
}

Add custom Function(s) to moduleExpressionFunctions

The moduleExpressionFunctions section is a Record with the Adaptable Modules as property keys and the property values of type (ModuleExpressionFunctionsMap)

Provide the functions relevant only for the Alert Module

Module specific functions override globally defined ones.

In this case, Alert.customBooleanFunctions override the global functions defined in customBooleanFunctions.

Define the module specific functions

The definition is exactly the same as for the global custom defined functions, each module may define its own:

systemBooleanFunctions
customBooleanFunctions
systemScalarFunctions
customScalarFunctions
systemObservableFunctions
systemAggregatedBooleanFunctions
systemAggregatedScalarFunctions

Provide functions relevant only for CalculatedColumn Module

Each Module specific functions override the global defined functions.

In this case, CalculatedColumn.customScalarFunctions override the global functions defined in ExpressionOptions.customScalarFunctions.

Define the module specific functions

The definition is exactly the same as for the global custom defined functions, each module may defined its own:

systemBooleanFunctions
customBooleanFunctions
systemScalarFunctions
customScalarFunctions
systemObservableFunctions
systemAggregatedBooleanFunctions
systemAggregatedScalarFunctions

AdapTableQL: Custom Functions Scope

Fork Fork

This example creates the same 2 Custom Expression Functions in the demo above.
However it uses the moduleExpressionFunctions property to limit where they can be applied (as explained in the Step by Step Guide above):
- the THIS_BUSINESS_YEAR Custom Boolean Expression Function is available only in the Alert Module
- the USD_CONVERT Custom Scalar Expression Function is available only in the Calculated Column Module

Expand to see the Definitions provided

  expressionOptions: {
    moduleExpressionFunctions: {
      Alert: {
        customBooleanFunctions: {
          THIS_BUSINESS_YEAR: {
            handler(args: any[], context: ExpressionContext) {
              const startBusinessYear = new Date(2023, 4, 1);
              return new Date(args[0]) > startBusinessYear;
            },
            returnType: 'boolean',
            description: 'Returns true if Date is in current Business year',
            signatures: ['THIS_BUSINESS_YEAR(dateToCheck: Date)'],
            examples: ['THIS_BUSINESS_YEAR([tradeDate])'],
          },
        },
      },
      CalculatedColumn: {
        customScalarFunctions: {
          USD_CONVERT: {
            handler(args, context: ExpressionContext) {
              const inputValue: number = args[0];
              if (isNaN(inputValue)) {
                return undefined;
              }
              const oldCurrency = args[1];
              if (oldCurrency === 'USD') {
                return inputValue;
              }

              if (oldCurrency === 'EUR') {
                return inputValue * 1.15;
              } else if (oldCurrency === 'GBP') {
                return inputValue * 1.2;
              }
              return undefined;
            },
            description: 'Converts EUR & GBP Currencies to Dollar',
            signatures: [
              'USD_CONVERT(currentValue: number, currentCurrency: string)',
            ],
            examples: [
              'USD_CONVERT([value],[currency])',
              'USD_CONVERT([value], "GBP")',
            ],
          },
        },
      },
  },
},

Try It Out

Open the Expression Editor and see the 2 custom Expression Functions in the Functions Dropdown
- THIS_BUSINESS_YEAR should be available only in the Alert Module
- USD_CONVERT should be available only in the CalculatedColumn Module

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Custom Expression Functions Scope',
  expressionOptions: {
    moduleExpressionFunctions: {
      Alert: {
        customBooleanFunctions: {
          THIS_BUSINESS_YEAR: {
            handler(args: any[], context: ExpressionContext) {
              const startBusinessYear = new Date(2023, 4, 1);
              return new Date(args[0]) > startBusinessYear;
            },
            returnType: 'boolean',
            description: 'Returns true if Date is in current Business year',
            signatures: ['THIS_BUSINESS_YEAR(dateToCheck: Date)'],
            examples: ['THIS_BUSINESS_YEAR([tradeDate])'],
          },
        },
      },
      CalculatedColumn: {
        customScalarFunctions: {
          USD_CONVERT: {
            handler(args, context: ExpressionContext) {
              const inputValue: number = args[0];
              if (isNaN(inputValue)) {
                return undefined;
              }
              const oldCurrency = args[1];
              if (oldCurrency === 'USD') {
                return inputValue;
              }

              if (oldCurrency === 'EUR') {
                return inputValue * 1.15;
              } else if (oldCurrency === 'GBP') {
                return inputValue * 1.2;
              }
              return undefined;
            },
            description: 'Converts EUR & GBP Currencies to Dollar',
            signatures: [
              'USD_CONVERT(currentValue: number, currentCurrency: string)',
            ],
            examples: [
              'USD_CONVERT([value],[currency])',
              'USD_CONVERT([value], "GBP")',
            ],
          },
        },
      },
    },
  },
  initialState: {
    Dashboard: {
      PinnedToolbars: ['GridFilter'],
      ModuleButtons: ['CalculatedColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-purchased',
          Scope: {
            ColumnIds: ['purchased'],
          },
          DisplayFormat: {
            Formatter: 'DateFormatter',
            Options: {
              Pattern: 'yyyy/MM/dd',
            },
          },
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: ['item', 'amount', 'currency', 'purchased'],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

PreviousCustom Aggregated Functions NextTechnical Reference

Framework: