diff --git a/docs/api/api_overview.md b/docs/api/api_overview.md index 498b7e9d..6baf5df2 100644 --- a/docs/api/api_overview.md +++ b/docs/api/api_overview.md @@ -25,6 +25,7 @@ Parameters: | Name | Description | | :------------------------------------------- | :-------------------------------------------------- | | [](api/spreadsheet_addcolumn_method.md) | @getshort(api/spreadsheet_addcolumn_method.md) | +| [](api/spreadsheet_addformula_method.md) | @getshort(api/spreadsheet_addformula_method.md) | | [](api/spreadsheet_addrow_method.md) | @getshort(api/spreadsheet_addrow_method.md) | | [](api/spreadsheet_addsheet_method.md) | @getshort(api/spreadsheet_addsheet_method.md) | | [](api/spreadsheet_clear_method.md) | @getshort(api/spreadsheet_clear_method.md) | diff --git a/docs/api/overview/methods_overview.md b/docs/api/overview/methods_overview.md index 6074a75e..dcf2c131 100644 --- a/docs/api/overview/methods_overview.md +++ b/docs/api/overview/methods_overview.md @@ -9,6 +9,7 @@ description: You can have a Methods overview of the DHTMLX JavaScript Spreadshee | Name | Description | | :------------------------------------------ | :------------------------------------------------- | | [](../spreadsheet_addcolumn_method.md) | @getshort(../spreadsheet_addcolumn_method.md) | +| [](../spreadsheet_addformula_method.md) | @getshort(../spreadsheet_addformula_method.md) | | [](../spreadsheet_addrow_method.md) | @getshort(../spreadsheet_addrow_method.md) | | [](../spreadsheet_addsheet_method.md) | @getshort(../spreadsheet_addsheet_method.md) | | [](../spreadsheet_clear_method.md) | @getshort(../spreadsheet_clear_method.md) | diff --git a/docs/api/spreadsheet_addformula_method.md b/docs/api/spreadsheet_addformula_method.md new file mode 100644 index 00000000..6cd82cd7 --- /dev/null +++ b/docs/api/spreadsheet_addformula_method.md @@ -0,0 +1,55 @@ +--- +sidebar_label: addFormula() +title: addFormula method +description: You can learn about the addFormula method in the documentation of the DHTMLX JavaScript Spreadsheet library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Spreadsheet. +--- + +# addFormula() + +### Description + +@short: Registers a custom formula function that can be used in cell formulas + +Once registered, the formula is available in any cell by its uppercase name (e.g. =MYFUNC(A1, B2)). + +### Usage + +~~~jsx +type cellValue = string | number | boolean +type mathArgument = cellValue | cellValue[]; +type mathFunction = (...x: mathArgument[]) => cellValue; + +addFormula: (name: string, handler: mathFunction) => void; +~~~ + +### Parameters + +- `name` - (*string*) required, the formula name (case-insensitive, stored as uppercase) +- `handler` - (*mathFunction*) required, a callback function that processes the input arguments (strings, numbers, booleans, or arrays of these) and returns a single value + +:::note +The `handler` callback function must be synchronous. Using `Promise` or `fetch` inside the function is not allowed. +::: + +### Example + +~~~jsx {4-6} +const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {}); + +// adds a custom formula that doubles a value +spreadsheet.addFormula("DOUBLE", (value) => { + return value * 2; +}); + +// now use in cells: =DOUBLE(A1) +spreadsheet.parse([ + { cell: "A1", value: 4, format: "number" }, + { cell: "B1", value: "=DOUBLE(A1)", format: "number" } +]); +~~~ + +**Change log:** Added in v6.0 + +**Related sample:** [Spreadsheet. Custom formula](https://snippet.dhtmlx.com/wvxdlahp) + +**Related articles:** [Formulas and functions](/functions/#custom-formulas) diff --git a/docs/functions.md b/docs/functions.md index dc7ecc3b..95825118 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -1326,4 +1326,31 @@ When you enter a formula, a popup with description of the function and its param Check the example in our [snippet tool](https://snippet.dhtmlx.com/wux2b35b). -You can modify the default locale for the popup with formula parameters and add a custom locale. Check the details in the [Localization](localization.md/#default-locale-for-formulas) guide. \ No newline at end of file +You can modify the default locale for the popup with formula parameters and add a custom locale. Check the details in the [Localization](localization.md/#default-locale-for-formulas) guide. + +## Custom formulas + +Starting with v6.0, you can register custom formula functions via the [`addFormula()`](api/spreadsheet_addformula_method.md) method. Once registered, the formula is available in any cell by its uppercase name. + +The method takes two parameters: the formula name and a synchronous handler function that receives the resolved cell values as arguments and returns the result: + +~~~js +spreadsheet.addFormula("DOUBLE", (value) => { + return value * 2; +}); +~~~ + +After that, the formula can be used in cells just like any built-in function: + +~~~js +spreadsheet.parse([ + { cell: "A1", value: 4, format: "number" }, + { cell: "B1", value: "=DOUBLE(A1)", format: "number" } +]); +~~~ + +:::note +The handler function must be synchronous. Using `Promise` or `fetch` inside the function is not allowed. +::: + +**Related sample:** [Spreadsheet. Custom formula](https://snippet.dhtmlx.com/wvxdlahp) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 92cb76ca..18fdec65 100644 --- a/sidebars.js +++ b/sidebars.js @@ -48,6 +48,7 @@ module.exports = { }, items: [ "api/spreadsheet_addcolumn_method", + "api/spreadsheet_addformula_method", "api/spreadsheet_addrow_method", "api/spreadsheet_addsheet_method", "api/spreadsheet_clear_method",