FormulaBuilder
See the Formula builder guide for examples and configuration details.
Description
Options
formulaBuilder
Can be set at: grid
formulaBuilder.formulaBuilder : object | boolean
The formulaBuilder option configures the FormulaBuilder plugin.
The FormulaBuilder plugin adds spreadsheet-style formula
editing (a formula bar, an inline formula editor with colored references, reference
picking, and formula error indicators) on top of the Formulas plugin,
which must be enabled with a configured engine.
You can set the formulaBuilder option to false (the plugin is off) or to an object with the
following properties. There is no true: the plugin needs the builder module to run. The plugin
logs a warning and stays disabled for true, for {}, and for an object without builder,
although validateSettings() accepts all three.
| Property | Possible values |
|---|---|
builder | The hyperformula-ui module namespace (import * as FormulaBuilderModule from 'hyperformula-ui'). Required. |
showFormulaBar | A boolean. Renders the formula bar above the grid when true. Default: false. |
popups | An object with the popup options: showClose, suggestions, fnHelp, and error. |
direction | 'ltr' or 'rtl'. The layout direction of the editor and its popups. Default: the grid’s layout direction. |
Formula editing is opt-in per cell: set editor to 'formula' on the cells,
columns, or grid that use the formula editor.
Read more:
This option can only be set at the grid level.
It has no effect when set in the columns, cells, or cell options.
Default: undefined
Since: 19.0.0
Example
import * as FormulaBuilderModule from 'hyperformula-ui';import { HyperFormula } from 'hyperformula';
// the formula editor on every celleditor: 'formula',formulas: { engine: HyperFormula,},formulaBuilder: { builder: FormulaBuilderModule, showFormulaBar: true,},Members
EDITORS
FormulaBuilder.EDITORS
The editor aliases the plugin provides. validateSettings() accepts them for a registered
plugin before any grid exists, while the editor registry learns them from the first instance.
LICENSE
FormulaBuilder.LICENSE
Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.
PLUGIN_DEPS
FormulaBuilder.PLUGIN_DEPS
Returns the list of plugin dependencies required before this plugin can be initialized.
PLUGIN_KEY
FormulaBuilder.PLUGIN_KEY
Returns the plugin key used to identify this plugin in Handsontable settings.
PLUGIN_PRIORITY
FormulaBuilder.PLUGIN_PRIORITY
Returns the priority order used to determine the order in which plugins are initialized.
SETTING_KEYS
FormulaBuilder.SETTING_KEYS
Returns the setting keys that, when present in an updateSettings config object, trigger
the plugin update. formulas is included because the plugin borrows the engine from the
Formulas plugin at enable time - a Formulas reconfiguration must re-run the enable cycle
so the plugin never keeps a stale engine reference.
Methods
attachFnHelpHost
formulaBuilder.attachFnHelpHost(container)
Re-parents the function help popup into a custom host element.
| Param | Type | Description |
|---|---|---|
| container | HTMLElement string | The host element or a CSS selector. |
attachSuggestionsHost
formulaBuilder.attachSuggestionsHost(container)
Re-parents the suggestions popup into a custom host element.
| Param | Type | Description |
|---|---|---|
| container | HTMLElement string | The host element or a CSS selector. |
destroy
formulaBuilder.destroy()
Destroy plugin instance.
detachFnHelpHost
formulaBuilder.detachFnHelpHost()
Restores the function help popup to its default anchored placement.
detachSuggestionsHost
formulaBuilder.detachSuggestionsHost()
Restores the suggestions popup to its default anchored placement.
disablePlugin
formulaBuilder.disablePlugin()
Disable plugin for this Handsontable instance.
enablePlugin
formulaBuilder.enablePlugin()
Enable plugin for this Handsontable instance.
getRawCellText
formulaBuilder.getRawCellText(row, col) ⇒ string
Returns the raw cell text: the formula source of a formula cell, or the stringified value.
| Param | Type | Description |
|---|---|---|
| row | number | The visual row index. |
| col | number | The visual column index. |
isEnabled
formulaBuilder.isEnabled() ⇒ boolean
Check if the plugin is enabled in the handsontable settings.
updatePlugin
formulaBuilder.updatePlugin()
Update plugin state after Handsontable settings update. A settings update that changes
nothing the plugin was built from keeps the built plugin (see AppliedConfig in the source).