An implementation of a reusable formula engine with javascript & sql generation along with Salesforce-approved syntax.
For the end-user documentation of the formula engine's functionality, please see the end-user facing documentation.
In order to implement this formula engine in your application, you need to
-
Include grammaticus, formula-engine-api, and formula-engine-impl in your application.
-
Look at FormulaEngineHooks, FormulaValidationHooks and implement the needed ones for your application during initialization.
-
Think about your type system. You'll need a
Class
that represents the type along with a FormulaDataType implementation that's used manage type conversion and error handling. You'll need something like MockFormulaDataType in your application, but if you're only handling strings, it can be simple. -
Override the
FormulaFactoryImpl
, probably addingFieldReferenceCommandInfo
andDynamicReference
to the commands, along with whichever implementations of FormulaCommandInfo you need for your application. -
Have a grammaticus localizer for any exception handling. For the minimum work, copy the
MockLocalizerContext
included in the test code, set theLocalizerFactory
at the start of your application. You may want to overrideFormulaValidationHooks.getLocalizer()
to return the same localizer. -
Implement a
FormulaTypeSpec
implementation that returns a valid getDefaultProperties, probably as an Enum. If you want different type of formulas in your application, make it an Enum like inMockFormulaType
. If you want javascript generated for mobile/offline use, you'll need to override that here. -
Create a
FormulaContext
that represents your data providers. Make sure your root context implementsgetProperty
,setProperty
,getFormulaReturnType
,isFunctionSupported
as they will be called in all circumstances. ExtendingBaseCompositeFormulaContext
is probably easisest for your Root/Default formula context. ThenaddContextProvider
for the various stuff you include -
The formula engine can parse hierarchies like
Contact.Account.Name
, but each formula context will get a chance to return the field at each point of the hierarchy, so you can override the results -
You can use different formula engines for compliation in
FormulaEngine.getFactory().create(...)
and then reuse that with different runtime contexts when you callgetFormula().evaluate(...)
. This lets you reuse the FormulaInfo multiple times, as formula parsing is somewhat expensive. If you want to handle the type conversions yourself, callevaluateRaw
, notevaluate
on the formulas. -
If you're using javascript, you need to have a few functions installed in the contexnt of the org, usually as
$F
. SeeFormulaJsTestUtils.getFunctionScript()
for the examples. You'll also want to load the includeddecimal.js
if you want high precision decimals client side, suitable for currencies.