FormulaProvider

Base class for formula providers which are classes which may be attached to an inputField and configured with a record from which it will pull the values of fields references by $fieldName in any evaluated formula typed into the inputField.

A inputField may be configured with an dataField. The referenced DataField may itself be configured with a formulaProviders object which maps formula provider prefixes to configuration objects. When the inputField is mutated, if it starts with =<prefix>( then a FormulaProvider registered under that prefix will be instantiated and used to evaluate the input value upon change (which fires on blur).

They may also be configured with a store which is used when the $data token is used in a formula to represent the JSON string of the whole dataset.

By default, a formula will be evaluated by passing it to the configured url as the paramName parameter in a POST request. The response will be expected to be a JSON object from which the value of the responseField will be used as the result of the formula.

An implementation may provide a generateContent callback which accepts the input field's formula value with referenced record field names substituted in. The generateContent callback must return a value based on that string.

An implementation may monitor the input field, and upon change, may use the field's value, and its record to calculate a new value in its handleFormulaChange method.

The value passed to handleFormulaChange has the following substitutions made:

$fieldName tokens replaced by the value of the named field from the configured record
$this token replaced by a JSON representation of the string values of the record
$data token replaced by a JSON representation of all records in the configured store

An implementation may implement a handleFormulaInput method to be notified upon any mutation of its inputField.

Data Fields and Formula Providers

When updating a DataField that contains a formula, a special sibling DataField is created to store the formula.

export default class Product extends Model {
    static fields = [
        'name',
        {
             name             : 'seoDescription',
             formulaProviders : {
                 AI   : {
                     url  : './myAIServerEndpoint.php',
                 }
             }
         }
    ];
});

const myModel = new Product({
    name : 'FitPro Adjustable Dumbbells'
});

// Setting a formula value of the field which has a formulaProvider will automatically trigger a call to the `url`
// from the formulaProvider to get the result, which is then stored in the `seoDescription` data field. The formula
// is then stored in the sibling field prepended with a '#'.
myProduct.set('seoDescription', '=AI(Generate 10 word SEO description for $name)');

When you persist a Model with a formula field, the formula field is stored as a sibling field to the formula field. The serialized JSON of a record having a seoDescription formula field would look like this:

 {
    "brand"           : "FitPro",
    "seoDescription"  : "Compact, versatile adjustable dumbbells for efficient home strength training workouts.",
    "#seoDescription" : "=AI(Generate 10 word SEO description for $name)",
  }

Configs

Common

listenersEvents

Other

fetchOptions: FetchOptions

An object containing the Fetch options to pass to the server request. Use this to control if credentials are sent and other options, read more at MDN.

headers: Object= {"Accept":"application/json","undefined":"application/json"}Also a property

The headers to send with the request.

inputField: TextFieldAlso a property

The input field which provides the formula.

This field becomes this object's owner, so that it can be used as the thisObj for callbacks.

If this FormulaProvider was created from a known type, for example the input field was configured with

    formulaConfig : {
        type   : 'aiformula',
        url    : 'https://aimodule.com/',
        apiKey : 'XXXXXXX'
    }

then the field value is taken to always represent a formula, and the entire string is used when passing the formula to handleFormulaChange.

If this FormulaProvider was inferred from the inputField's value starting with a formula prefix (eg =AI(), then the string between the parentheses is used and handleFormulaChange is only called if the value matches eg =AI(.*).

$fieldName tokens replaced by the value of the named field from the configured record
$this token replaced by a JSON representation of the string values of the record
$data token replaced by a JSON representation of all records in the configured store

method: String= POSTAlso a property

The HTTP method to use when sending the formula to the server.

paramName: String= promptAlso a property

The name of the property in the JSON object sent to the server which contains the formula.

It may be a dot-separated path to inject a nested value.

record: ModelAlso a property

The Record from which this formula provider fetches field definitions and values

responseField: String= contentAlso a property

The name of the property in the JSON object received from the server which contains the result of the formula.

It may be a dot-separated path to a nested value.

Expected response format with the default value for this property ("content"):

{
  "content" : "Hello World!"
}

store: Store

The store from which this formula provider fetches field definitions. Defaults to the record's first store.

url: StringAlso a property

The URL to which the formula will be sent for evaluation in a JSON packet in a property named by paramName.

The response is expected to be a JSON object from which the value of the responseField will be used as the result of the formula.

{
  "content" : "Hello World!"
}

catchEventHandlerExceptionsEvents

Misc

bubbleEventsEvents

callOnFunctionsEvents

Properties

Class hierarchy

isFormulaProvider: Boolean= truereadonly

Identifies an object as an instance of FormulaProvider class, or subclass thereof.

isFormulaProvider: Boolean= truereadonlystatic

Identifies an object as an instance of FormulaProvider class, or subclass thereof.

isEventsEvents

Other

headers: Object= {"Accept":"application/json","undefined":"application/json"}Also a config

The headers to send with the request.

inputField: TextFieldAlso a config

The input field which provides the formula.

This field becomes this object's owner, so that it can be used as the thisObj for callbacks.

If this FormulaProvider was created from a known type, for example the input field was configured with

    formulaConfig : {
        type   : 'aiformula',
        url    : 'https://aimodule.com/',
        apiKey : 'XXXXXXX'
    }

then the field value is taken to always represent a formula, and the entire string is used when passing the formula to handleFormulaChange.

$fieldName tokens replaced by the value of the named field from the configured record
$this token replaced by a JSON representation of the string values of the record
$data token replaced by a JSON representation of all records in the configured store

method: String= POSTAlso a config

The HTTP method to use when sending the formula to the server.

paramName: String= promptAlso a config

The name of the property in the JSON object sent to the server which contains the formula.

It may be a dot-separated path to inject a nested value.

record: ModelAlso a config

The Record from which this formula provider fetches field definitions and values

responseField: String= contentAlso a config

The name of the property in the JSON object received from the server which contains the result of the formula.

It may be a dot-separated path to a nested value.

Expected response format with the default value for this property ("content"):

{
  "content" : "Hello World!"
}

url: StringAlso a config

The URL to which the formula will be sent for evaluation in a JSON packet in a property named by paramName.

The response is expected to be a JSON object from which the value of the responseField will be used as the result of the formula.

{
  "content" : "Hello World!"
}

catchEventHandlerExceptionsEvents

Lifecycle

configBase

isConstructingBase

isDestroyedBase

isDestroyingBase

Misc

callOnFunctionsEvents

Functions

Other

calculate

Processes the passed prompt using the configured generateContent or the configured url and returns the string result.

Note that this is an async function and the return value will need to be awaited.

Parameter	Type	Description
`prompt`	String

Returns: String

addListenerEvents

hasListenerEvents

onEvents

relayAllEvents

removeAllListenersEvents

removeListenerEvents

resumeEventsEvents

suspendEventsEvents

triggerEvents

unEvents

destroystaticBase

doDestroyBase

setConfigBase

Misc

animatePropertyBase

callbackBase

downloadTestCaseBase

initClassstaticBase

isOfTypeNamestaticBase

mixinstaticBase

resolveCallbackBase

Events

formulaChange

Fires when the formula source has been processed and is about to be used.

Referenced cell values have been substituted in.

A handler may change the formula property of the event object to modify the formula before it is used.

// Adding a listener using the "on" method
formulaProvider.on('formulaChange', ({ formula }) => {

});

Parameter	Type	Description
`formula`	String	The formula to be used. Replace this to change the formula.

formulaNetworkError

Fires when the network request to the server fails.

This event bubbles, so can be caught on the FormulaProvider instance, its owning inputField or any parent widget.

When this error occurs, the formula result will be an empty string.

// Adding a listener using the "on" method
formulaProvider.on('formulaNetworkError', ({ response }) => {

});

Parameter	Type	Description
`response`	Response	The response object from the failed request.

beforeDestroyEvents

catchAllEvents

destroyEvents

Event handlers

onFormulaChange

Called when the formula source has been processed and is about to be used.

Referenced cell values have been substituted in.

A handler may change the formula property of the event object to modify the formula before it is used.

new FormulaProvider({
    onFormulaChange({ formula }) {

    }
});

Parameter	Type	Description
`formula`	String	The formula to be used. Replace this to change the formula.

onFormulaNetworkError

Called when the network request to the server fails.

This event bubbles, so can be caught on the FormulaProvider instance, its owning inputField or any parent widget.

When this error occurs, the formula result will be an empty string.

new FormulaProvider({
    onFormulaNetworkError({ response }) {

    }
});

Parameter	Type	Description
`response`	Response	The response object from the failed request.

onBeforeDestroyEvents

onCatchAllEvents

onDestroyEvents

Typedefs

BryntumListenerConfigEvents

FormulaProvider

Data Fields and Formula Providers

Configs

Common

Other

Misc

Properties

Class hierarchy

Other

Lifecycle

Misc

Functions

Other

Configuration

Events

Lifecycle

Misc

Events

Event handlers

Typedefs