From 38fa738cc99090623e5113704b51f2ff683f7400 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Fri, 8 May 2026 16:43:45 +0300 Subject: [PATCH 1/4] [add] addFormula api page and a section in the related guide --- docs/api/api_overview.md | 1 + docs/api/overview/methods_overview.md | 1 + docs/api/spreadsheet_addformula_method.md | 47 +++++++++++++++++++++++ docs/functions.md | 27 ++++++++++++- sidebars.js | 1 + 5 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 docs/api/spreadsheet_addformula_method.md 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..6bd5c9e1 --- /dev/null +++ b/docs/api/spreadsheet_addformula_method.md @@ -0,0 +1,47 @@ +--- +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 +addFormula(name: string, handler: (...args: any[]) => any): void; +~~~ + +### Parameters + +- `name` - (*string*) required, the formula name (case-insensitive, stored as uppercase) +- `handler` - (*(...args: any[]) => any*) required, the function that computes the formula result. Receives the resolved cell values as arguments + +:::note +The `handler` callback function must be synchronous. Using `Promise` or `fetch` inside the function is not allowed. +::: + +### Example + +~~~jsx {5-8} +const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {}); +spreadsheet.parse(data); + +// adds a custom formula that doubles a value +spreadsheet.addFormula("DOUBLE", (value) => { + return value * 2; +}); +// Now use in cells: =DOUBLE(A1) +~~~ + +**Change log:** Added in v6.0 + +**Related sample:** [Spreadsheet. Custom formula](https://snippet.dhtmlx.com/wvxdlahp) + +**Related articles:** [Formulas and functions](functions.md) diff --git a/docs/functions.md b/docs/functions.md index dc7ecc3b..18676f23 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -1326,4 +1326,29 @@ 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", (arg) => arg * 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. +::: + + \ 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", From 1aa62cd2597fc948d5d42195bb199b9c3368bd84 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 11 May 2026 10:52:10 +0300 Subject: [PATCH 2/4] [update] addFormula page and related guide --- docs/api/spreadsheet_addformula_method.md | 12 ++++++++---- docs/functions.md | 2 +- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/api/spreadsheet_addformula_method.md b/docs/api/spreadsheet_addformula_method.md index 6bd5c9e1..387b6d7a 100644 --- a/docs/api/spreadsheet_addformula_method.md +++ b/docs/api/spreadsheet_addformula_method.md @@ -29,19 +29,23 @@ The `handler` callback function must be synchronous. Using `Promise` or `fetch` ### Example -~~~jsx {5-8} +~~~jsx {4-6} const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {}); -spreadsheet.parse(data); -// adds a custom formula that doubles a value +// 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.md) +**Related articles:** [Formulas and functions](/functions/#custom-formulas) diff --git a/docs/functions.md b/docs/functions.md index 18676f23..ac9027d1 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -1351,4 +1351,4 @@ spreadsheet.parse([ The handler function must be synchronous. Using `Promise` or `fetch` inside the function is not allowed. ::: - \ No newline at end of file +**Related sample:** [Spreadsheet. Custom formula](https://snippet.dhtmlx.com/wvxdlahp) \ No newline at end of file From dfba295fe627db51a9ebe0813d7ad0e620674d7f Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Mon, 11 May 2026 16:49:22 +0300 Subject: [PATCH 3/4] [update] improve addFormula code example - expand arrow function to block body with explicit return - rename parameter from arg to value for clarity --- docs/functions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/functions.md b/docs/functions.md index ac9027d1..95825118 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -1335,7 +1335,9 @@ Starting with v6.0, you can register custom formula functions via the [`addFormu 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", (arg) => arg * 2); +spreadsheet.addFormula("DOUBLE", (value) => { + return value * 2; +}); ~~~ After that, the formula can be used in cells just like any built-in function: From 05a771bdacc5425bc794ce1295e65476c576a623 Mon Sep 17 00:00:00 2001 From: Masha_Rudenko Date: Wed, 13 May 2026 17:09:45 +0300 Subject: [PATCH 4/4] [update] improve addFormula type definitions and style - replaced generic handler type with named type aliases (cellValue, mathArgument, mathFunction) - updated handler parameter description for clarity - fixed code comment capitalization to match project style --- docs/api/spreadsheet_addformula_method.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/api/spreadsheet_addformula_method.md b/docs/api/spreadsheet_addformula_method.md index 387b6d7a..6cd82cd7 100644 --- a/docs/api/spreadsheet_addformula_method.md +++ b/docs/api/spreadsheet_addformula_method.md @@ -15,13 +15,17 @@ Once registered, the formula is available in any cell by its uppercase name (e.g ### Usage ~~~jsx -addFormula(name: string, handler: (...args: any[]) => any): void; +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` - (*(...args: any[]) => any*) required, the function that computes the formula result. Receives the resolved cell values as arguments +- `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. @@ -32,12 +36,12 @@ The `handler` callback function must be synchronous. Using `Promise` or `fetch` ~~~jsx {4-6} const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {}); -// Adds a custom formula that doubles a value +// adds a custom formula that doubles a value spreadsheet.addFormula("DOUBLE", (value) => { return value * 2; }); -// Now use in cells: =DOUBLE(A1) +// now use in cells: =DOUBLE(A1) spreadsheet.parse([ { cell: "A1", value: 4, format: "number" }, { cell: "B1", value: "=DOUBLE(A1)", format: "number" }