Skip to content

FormulaBuilder

See the Formula builder guide for examples and configuration details.

Description

Options

formulaBuilder

Can be set at: grid

Source code

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.

PropertyPossible values
builderThe hyperformula-ui module namespace (import * as FormulaBuilderModule from 'hyperformula-ui'). Required.
showFormulaBarA boolean. Renders the formula bar above the grid when true. Default: false.
popupsAn 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 cell
editor: 'formula',
formulas: {
engine: HyperFormula,
},
formulaBuilder: {
builder: FormulaBuilderModule,
showFormulaBar: true,
},

Members

EDITORS

Source code

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

Source code

FormulaBuilder.LICENSE

Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.

PLUGIN_DEPS

Source code

FormulaBuilder.PLUGIN_DEPS

Returns the list of plugin dependencies required before this plugin can be initialized.

PLUGIN_KEY

Source code

FormulaBuilder.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Source code

FormulaBuilder.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

SETTING_KEYS

Source code

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

Source code

formulaBuilder.attachFnHelpHost(container)

Re-parents the function help popup into a custom host element.

ParamTypeDescription
containerHTMLElement
string
The host element or a CSS selector.

attachSuggestionsHost

Source code

formulaBuilder.attachSuggestionsHost(container)

Re-parents the suggestions popup into a custom host element.

ParamTypeDescription
containerHTMLElement
string
The host element or a CSS selector.

destroy

Source code

formulaBuilder.destroy()

Destroy plugin instance.

detachFnHelpHost

Source code

formulaBuilder.detachFnHelpHost()

Restores the function help popup to its default anchored placement.

detachSuggestionsHost

Source code

formulaBuilder.detachSuggestionsHost()

Restores the suggestions popup to its default anchored placement.

disablePlugin

Source code

formulaBuilder.disablePlugin()

Disable plugin for this Handsontable instance.

enablePlugin

Source code

formulaBuilder.enablePlugin()

Enable plugin for this Handsontable instance.

getRawCellText

Source code

formulaBuilder.getRawCellText(row, col) ⇒ string

Returns the raw cell text: the formula source of a formula cell, or the stringified value.

ParamTypeDescription
rownumberThe visual row index.
colnumberThe visual column index.

isEnabled

Source code

formulaBuilder.isEnabled() ⇒ boolean

Check if the plugin is enabled in the handsontable settings.

updatePlugin

Source code

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).