Standard Custom Expression Functions

View as Markdown

Summary

  • Standard Custom Expression Functions evaluate one row at a time
  • Boolean and value-producing functions share the same registration map
  • Each function is a flat object: evaluation props plus editor / availability metadata

Standard Custom Expression Functions are Expression Functions which are:

  • provided by developers at design-time
  • evaluated against a single row

Standard Custom Expression Functions are registered in expressionOptions.customStandardFunctions.

The function can return any value, e.g. boolean, number, string, date, object, any etc.

How It Works

  1. A developer registers a function on customStandardFunctions — at minimum a handler and a returnType
  2. AdapTableQL treats it like any other Standard Function and lists it in the Expression Editor
  3. Functions that return a Boolean and take 1 or 2 arguments will also be available in the Query Builder
  4. A run-time user (or Initial State) includes the function in an Expression
  5. AdapTableQL invokes the handler when it evaluates that Expression and returns the result

Hint

Editor-related properties (description, signatures, examples, category) are optional but strongly recommended

Developer Guide

Defining a Custom Expression Function

This Guide creates 2 Custom Functions:

  • THIS_BUSINESS_YEAR — returns a boolean (true or false)
  • USD_CONVERT — returns a number
// Expression Options
expressionOptions: {
  customStandardFunctions: {
    THIS_BUSINESS_YEAR: {
      handler(args: any[], context: ExpressionContext) {
        const startBusinessYear = new Date(2023, 4, 1);
        return new Date(args[0]) > startBusinessYear;
      },
      returnType: 'boolean',
      operands: [['date']],
      description: 'Returns true if Date is in current Business year',
      signatures: ['THIS_BUSINESS_YEAR(dateToCheck: Date)'],
      examples: ['THIS_BUSINESS_YEAR([tradeDate])'],
      category: 'custom',
    },
    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;
      },
      returnType: 'number',
      operands: [['number', 'text']],
      description: 'Converts EUR & GBP Currencies to Dollar',
      signatures: ['USD_CONVERT(val: number, ccy: string)'],
      examples: [
        'USD_CONVERT([value],[currency])',
        'USD_CONVERT([value], "GBP")',
      ],
      category: 'custom',
    },
  },
}
1
Add functions to Expression Options

Add each function to expressionOptions.customStandardFunctions.

It is a Record (or a callback that returns one) with:

2
Provide the name of the Function

By convention the Function name is in CAPITAL LETTERS — it is more readable when used in an Expression.

3
Supply the handler

handler is the actual function implementation.

It receives an args array and an ExpressionContext, and returns the function result (boolean, number, or any other value).

4
Set returnType

returnType is required on custom Standard functions.

Use a value from EXPRESSION_RETURN_TYPES ('boolean' | 'number' | 'string' | 'date' | 'object' | 'null' | 'any')

5
Declare operands

operands is the type / input number matrix.

This drives expression validation.

For booleans, its responsible for if and how it should appear in the Query Builder and Column Filter (not just the Expression Editor).

  • THIS_BUSINESS_YEAR takes one date (the column)
  • USD_CONVERT takes a number and a string
6
Provide editor help

These 4 properties are used to provide context support in the Expression Editor:

  • description — what the Function does
  • signatures — how it should be called
  • examples — small Expressions that use it
  • category — which Functions menu it appears in (e.g. 'date', 'numeric')

Hint

  • Omit or use 'custom' for the Custom menu
  • Any other string creates a menu with that name

Expression Function Object

Each Standard Custom Function is an AdaptableCustomExpressionFunction: one flat object that combines AQL evaluation properties with AdapTable presentation / availability properties.

Caution

Ensure the custom function uses AdaptableCustomExpressionFunction or AdaptableCustomExpressionFunctionEntry

Deep Dive

Authoring properties

Hint

  • Provide the editor-facing properties even when they are optional
  • They are what run-time users see when they pick the function.

Query Builder and Column Filter

A custom boolean function will also appear in Query Builder and Column Filter if:

  • returnType is 'boolean'
  • the number of operands is 1 (column only) or 2 (column + value)

Note

  • Optional label / icon are used in the operator picker
  • rhs refines the value editor for the non-subject operand

Expression Function handler

handler is the implementation and is of type ExpressionFunctionHandler.

Together with returnType it is the only required property.

(args: any[], context: ExpressionContext) => any;
  • args — the function’s arguments, already evaluated (column values, literals, nested results)
  • context — public ExpressionContext (AdaptableExpressionContext)
Deep Dive

What to use on context

Inheriting a system function

A Custom function can inherit from an existing System Function.

In this case, the function is partial and uses extends (ExpressionFunctionPartialWithExtends).

Note

  • Unspecified fields are copied from the named system (or already-registered custom) function
  • This is useful when overriding a function's handler, while keeping its label, icon and operands
customStandardFunctions: {
  IS_BLANK: {
    extends: 'IS_BLANK',
    handler(args, context) {
      const value = args[0];
      return value == null || value === '';
    },
  },
}
AdapTableQL: Custom Standard Functions
Fork
  • This example creates 2 Custom Standard Expression Functions — used in a table showing (random) purchases:
    • THIS_BUSINESS_YEAR — boolean (returnType: 'boolean', one date operand) — true if the Date is after 1 April 2023
    • USD_CONVERT — value-producing — fictitiously converts EUR and GBP amounts to Dollars
  • They are referenced in other Modules:
    • THIS_BUSINESS_YEAR in a Format Column which puts matching rows in Bold, Italics and a Blue Font
    • USD_CONVERT in the Dollar Price Calculated Column
    • Both functions are referenced in the Old High Exchange Named Query

Expand to see the Definitions provided

Try It Out
  • Open the Expression Editor and see the 2 custom Functions in the Custom menu
  • Open Column Filter on purchased — THIS_BUSINESS_YEAR is offered as an operator (boolean + one date operand)
  • USD_CONVERT stays Expression-Editor-only (it is not a boolean)
Loading demo…

Defining Custom Expression Functions

Custom functions are registered in expressionOptions.customStandardFunctions.

Hint

To limit which Modules can use a function, set isAvailable — see Custom Expression Function Scope

customStandardFunctions

Default: undefined
Record<string, AdaptableCustomExpressionFunctionEntry>
Custom Standard Expression Functions available in AdapTableQL

FAQ

Does the Custom Expression Function's name have to be capitalised? No, it is not mandatory, but it is a convention we encourage, as it makes the Expression more readable.

Will my boolean function appear in Query Builder and Column Filter? Yes, but only if you set returnType: 'boolean' and have only 1 or 2 operands; otherwise it is Expression-Editor-only.

Can I limit the function to some Modules? Yes — set isAvailable on the function (or use expressionOptions.isExpressionFunctionAvailable). See Custom Expression Function Scope for full details.