Standard Custom Expression Functions
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
- A developer registers a function on
customStandardFunctions— at minimum ahandlerand areturnType - AdapTableQL treats it like any other Standard Function and lists it in the Expression Editor
- Functions that return a Boolean and take 1 or 2 arguments will also be available in the Query Builder
- A run-time user (or Initial State) includes the function in an Expression
- AdapTableQL invokes the
handlerwhen 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',
},
},
}Add each function to expressionOptions.customStandardFunctions.
It is a Record (or a callback that returns one) with:
- keys: custom function names
- values: can be either a full
AdaptableCustomExpressionFunction, or a partial thatextendsanother function
By convention the Function name is in CAPITAL LETTERS — it is more readable when used in an Expression.
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).
returnType is required on custom Standard functions.
Use a value from EXPRESSION_RETURN_TYPES ('boolean' | 'number' | 'string' | 'date' | 'object' | 'null' | 'any')
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_YEARtakes one date (the column)USD_CONVERTtakes a number and a string
These 4 properties are used to provide context support in the Expression Editor:
description— what the Function doessignatures— how it should be calledexamples— small Expressions that use itcategory— 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:
returnTypeis'boolean'- the number of
operandsis 1 (column only) or 2 (column + value)
Note
- Optional
label/iconare used in the operator picker rhsrefines 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— publicExpressionContext(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 === '';
},
},
}- 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 2023USD_CONVERT— value-producing — fictitiously converts EUR and GBP amounts to Dollars
- They are referenced in other Modules:
THIS_BUSINESS_YEARin a Format Column which puts matching rows in Bold, Italics and a Blue FontUSD_CONVERTin theDollar PriceCalculated Column- Both functions are referenced in the
Old High ExchangeNamed Query
Expand to see the Definitions provided
- Open the Expression Editor and see the 2 custom Functions in the Custom menu
- Open Column Filter on
purchased—THIS_BUSINESS_YEARis offered as an operator (boolean + one date operand) USD_CONVERTstays Expression-Editor-only (it is not a boolean)
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: undefinedRecord<string, AdaptableCustomExpressionFunctionEntry>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.