From c97f8a8613378ea660d3d4d80a35a63134acc88f Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 21 Jun 2024 13:07:45 -0700 Subject: [PATCH 1/7] [Excel] (Custom functions) Add new cell value type JSON parameter --- docs/excel/custom-functions-json-autogeneration.md | 8 +++++++- docs/excel/custom-functions-json.md | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/excel/custom-functions-json-autogeneration.md b/docs/excel/custom-functions-json-autogeneration.md index 9426190dba..4e03506a89 100644 --- a/docs/excel/custom-functions-json-autogeneration.md +++ b/docs/excel/custom-functions-json-autogeneration.md @@ -1,7 +1,7 @@ --- title: Autogenerate JSON metadata for custom functions description: Use JSDoc tags to dynamically create your custom functions JSON metadata. -ms.date: 07/11/2023 +ms.date: 06/21/2024 ms.localizationpriority: medium --- @@ -409,6 +409,12 @@ A streaming function can indicate an error by calling `setResult()` with an Erro A custom function can return a promise that provides the value when the promise is resolved. If the promise is rejected, then the custom function will throw an error. +### Cell value type + +JavaScript Syntax: @param {any} [cellValueType] name description + +Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are ??, ??, ??. + ### Other types Any other type will be treated as an error. diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index 247cc8b1d1..69004f1070 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -1,7 +1,7 @@ --- title: Manually create JSON metadata for custom functions in Excel description: Define JSON metadata for custom functions in Excel and associate your function ID and name properties. -ms.date: 10/10/2022 +ms.date: 06/21/2024 ms.localizationpriority: medium --- From 554bb92799681f9b61fd7e3f05bde5c38ca6718c Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 21 Jun 2024 13:11:59 -0700 Subject: [PATCH 2/7] [Excel] (Custom functions) Add new cell value type JSON parameter --- docs/excel/custom-functions-json.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index 69004f1070..32e126172e 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -185,9 +185,22 @@ The `parameters` property is an array of parameter objects. The following table | `dimensionality` | string | No | Must be either `scalar` (a non-array value) or `matrix` (a 2-dimensional array). | | `name` | string | Yes | The name of the parameter. This name is displayed in Excel's IntelliSense. | | `type` | string | No | The data type of the parameter. Can be `boolean`, `number`, `string`, or `any`, which allows you to use of any of the previous three types. If this property is not specified, the data type defaults to `any`. | +| `cellValueType` | string | No | A subfield of the `type` property. Specifies the Excel data types accepted by the custom function. Accepts the values ??, ??, ??. The `type` field must have the value `any` to use the `cellValueType` subfield. | | `optional` | boolean | No | If `true`, the parameter is optional. | |`repeating`| boolean | No | If `true`, parameters populate from a specified array. Note that functions all repeating parameters are considered optional parameters by definition. | +> [!TIP] +> See the following code snippet for an example of how to format the `cellValueType` parameter. +> ```json +> "parameters": [ +> { +> "name": "range", +> "description": "the input range", +> "type": "any", /* A `type` value of `any` is required to use the `cellValueType` sub-field. */ +> "cellValueType": "??" +> } +> ] + ### result The `result` object defines the type of information that is returned by the function. The following table lists the properties of the `result` object. From 9d0eda0ce8322d69eeb76c9bd683509d02c724d8 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 21 Jun 2024 13:12:53 -0700 Subject: [PATCH 3/7] Add closing code ticks --- docs/excel/custom-functions-json.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index 32e126172e..edee702722 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -200,7 +200,8 @@ The `parameters` property is an array of parameter objects. The following table > "cellValueType": "??" > } > ] - +> ``` + ### result The `result` object defines the type of information that is returned by the function. The following table lists the properties of the `result` object. From 5d37c963bc2f1a79d1796e1d17aebea20b9eaf49 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 18 Oct 2024 15:51:06 -0700 Subject: [PATCH 4/7] Add cell value type values --- docs/excel/custom-functions-json-autogeneration.md | 4 ++-- docs/excel/custom-functions-json.md | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/excel/custom-functions-json-autogeneration.md b/docs/excel/custom-functions-json-autogeneration.md index 4e03506a89..5962ddc009 100644 --- a/docs/excel/custom-functions-json-autogeneration.md +++ b/docs/excel/custom-functions-json-autogeneration.md @@ -1,7 +1,7 @@ --- title: Autogenerate JSON metadata for custom functions description: Use JSDoc tags to dynamically create your custom functions JSON metadata. -ms.date: 06/21/2024 +ms.date: 10/18/2024 ms.localizationpriority: medium --- @@ -413,7 +413,7 @@ A custom function can return a promise that provides the value when the promise JavaScript Syntax: @param {any} [cellValueType] name description -Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are ??, ??, ??. +Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are: `Excel.CellValue`, `Excel.BooleanCellValue`, `Excel.DoubleCellValue`, `Excel.EntityCellValue`, `Excel.ErrorCellValue`, `Excel.FormattedNumberCellValue`, `Excel.LinkedEntityCellValue`, `Excel.LocalImageCellValue`, `Excel.StringCellValue`, and `Excel.WebImageCellValue`. ### Other types diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index edee702722..8a612dcda3 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -1,7 +1,7 @@ --- title: Manually create JSON metadata for custom functions in Excel description: Define JSON metadata for custom functions in Excel and associate your function ID and name properties. -ms.date: 06/21/2024 +ms.date: 10/18/2024 ms.localizationpriority: medium --- @@ -185,7 +185,8 @@ The `parameters` property is an array of parameter objects. The following table | `dimensionality` | string | No | Must be either `scalar` (a non-array value) or `matrix` (a 2-dimensional array). | | `name` | string | Yes | The name of the parameter. This name is displayed in Excel's IntelliSense. | | `type` | string | No | The data type of the parameter. Can be `boolean`, `number`, `string`, or `any`, which allows you to use of any of the previous three types. If this property is not specified, the data type defaults to `any`. | -| `cellValueType` | string | No | A subfield of the `type` property. Specifies the Excel data types accepted by the custom function. Accepts the values ??, ??, ??. The `type` field must have the value `any` to use the `cellValueType` subfield. | +| `cellValueType` | string | No | A subfield of the `type` property. Specifies the Excel data types accepted by the custom function. Accepts the case-insensitive values `cellvalue`, `booleancellvalue`, `doublecellvalue`, `entitycellvalue`, `errorcellvalue`, `formattednumbercellvalue`, `linkedentitycellvalue`, `localimagecellvalue`, `stringcellvalue`,and `webimagecellvalue`. +

The `type` field must have the value `any` to use the `cellValueType` subfield. | | `optional` | boolean | No | If `true`, the parameter is optional. | |`repeating`| boolean | No | If `true`, parameters populate from a specified array. Note that functions all repeating parameters are considered optional parameters by definition. | From 0bb357cb4e6bfc20920b6e43999f1e1c441e1ccd Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 18 Oct 2024 16:16:19 -0700 Subject: [PATCH 5/7] Minor adjustments --- .../custom-functions-data-types-concepts.md | 4 +-- .../custom-functions-json-autogeneration.md | 25 +++++++++++++------ docs/excel/custom-functions-json.md | 3 +-- 3 files changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/excel/custom-functions-data-types-concepts.md b/docs/excel/custom-functions-data-types-concepts.md index 1909f316b5..4d13a10917 100644 --- a/docs/excel/custom-functions-data-types-concepts.md +++ b/docs/excel/custom-functions-data-types-concepts.md @@ -1,7 +1,7 @@ --- title: Custom functions and data types description: Use Excel data types with your custom functions and Office Add-ins. -ms.date: 10/17/2022 +ms.date: 10/18/2024 ms.topic: overview ms.custom: scenarios:getting-started ms.localizationpriority: medium @@ -57,7 +57,7 @@ The following code sample shows a custom function that takes an [EntityCellValue /** * Accept an entity value data type as a function input. * @customfunction - * @param {any} value + * @param {Excel.EntityCellValue} value * @param {string} attribute * @returns {any} The text value of the entity. */ diff --git a/docs/excel/custom-functions-json-autogeneration.md b/docs/excel/custom-functions-json-autogeneration.md index 5962ddc009..20b0845123 100644 --- a/docs/excel/custom-functions-json-autogeneration.md +++ b/docs/excel/custom-functions-json-autogeneration.md @@ -34,7 +34,7 @@ The plugin is [CustomFunctionsMetadataPlugin](https://github.com/OfficeDev/Offic ### Multiple custom function source files -If, and only if, you have organized your custom functions into multiple source files, there are additional steps. +If, and only if, you have organized your custom functions into multiple source files, there are additional steps. 1. In the webpack.config.js file, replace the string value of `input` with an array of string URLs that point to each of the files. The following is an example: @@ -395,6 +395,23 @@ By specifying a parameter type, Excel will convert values into that type before A single value may be represented using one of the following types: `boolean`, `number`, `string`. +### Cell value type + +JavaScript Syntax: @param {any} *[cellValueType]* name description + +Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are: + +- `Excel.CellValue` +- `Excel.BooleanCellValue` +- `Excel.DoubleCellValue` +- `Excel.EntityCellValue` +- `Excel.ErrorCellValue` +- `Excel.FormattedNumberCellValue` +- `Excel.LinkedEntityCellValue` +- `Excel.LocalImageCellValue` +- `Excel.StringCellValue` +- `Excel.WebImageCellValue` + ### Matrix type Use a two-dimensional array type to have the parameter or return value be a matrix of values. For example, the type `number[][]` indicates a matrix of numbers and `string[][]` indicates a matrix of strings. @@ -409,12 +426,6 @@ A streaming function can indicate an error by calling `setResult()` with an Erro A custom function can return a promise that provides the value when the promise is resolved. If the promise is rejected, then the custom function will throw an error. -### Cell value type - -JavaScript Syntax: @param {any} [cellValueType] name description - -Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are: `Excel.CellValue`, `Excel.BooleanCellValue`, `Excel.DoubleCellValue`, `Excel.EntityCellValue`, `Excel.ErrorCellValue`, `Excel.FormattedNumberCellValue`, `Excel.LinkedEntityCellValue`, `Excel.LocalImageCellValue`, `Excel.StringCellValue`, and `Excel.WebImageCellValue`. - ### Other types Any other type will be treated as an error. diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index 8a612dcda3..6a983bc272 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -185,8 +185,7 @@ The `parameters` property is an array of parameter objects. The following table | `dimensionality` | string | No | Must be either `scalar` (a non-array value) or `matrix` (a 2-dimensional array). | | `name` | string | Yes | The name of the parameter. This name is displayed in Excel's IntelliSense. | | `type` | string | No | The data type of the parameter. Can be `boolean`, `number`, `string`, or `any`, which allows you to use of any of the previous three types. If this property is not specified, the data type defaults to `any`. | -| `cellValueType` | string | No | A subfield of the `type` property. Specifies the Excel data types accepted by the custom function. Accepts the case-insensitive values `cellvalue`, `booleancellvalue`, `doublecellvalue`, `entitycellvalue`, `errorcellvalue`, `formattednumbercellvalue`, `linkedentitycellvalue`, `localimagecellvalue`, `stringcellvalue`,and `webimagecellvalue`. -

The `type` field must have the value `any` to use the `cellValueType` subfield. | +| `cellValueType` | string | No | A subfield of the `type` property. Specifies the Excel data types accepted by the custom function. Accepts the case-insensitive values `cellvalue`, `booleancellvalue`, `doublecellvalue`, `entitycellvalue`, `errorcellvalue`, `formattednumbercellvalue`, `linkedentitycellvalue`, `localimagecellvalue`, `stringcellvalue`, and `webimagecellvalue`.

The `type` field must have the value `any` to use the `cellValueType` subfield. | | `optional` | boolean | No | If `true`, the parameter is optional. | |`repeating`| boolean | No | If `true`, parameters populate from a specified array. Note that functions all repeating parameters are considered optional parameters by definition. | From 40c88926a81c4d97096ef157cc7cb6c66a9e7eca Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 18 Oct 2024 16:42:18 -0700 Subject: [PATCH 6/7] Clarify new cell value type rules --- docs/excel/custom-functions-json-autogeneration.md | 4 ++-- docs/excel/custom-functions-json.md | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/excel/custom-functions-json-autogeneration.md b/docs/excel/custom-functions-json-autogeneration.md index 20b0845123..fe87299c28 100644 --- a/docs/excel/custom-functions-json-autogeneration.md +++ b/docs/excel/custom-functions-json-autogeneration.md @@ -397,8 +397,6 @@ A single value may be represented using one of the following types: `boolean`, ` ### Cell value type -JavaScript Syntax: @param {any} *[cellValueType]* name description - Use the `type` subfield `cellValueType` to specify that a custom function accept and return Excel data types. The `type` value must be `any` to use the `cellValueType` subfield. Accepted `cellValueType` values are: - `Excel.CellValue` @@ -412,6 +410,8 @@ Use the `type` subfield `cellValueType` to specify that a custom function accept - `Excel.StringCellValue` - `Excel.WebImageCellValue` +For a code sample using the `Excel.EntityCellValue` type, see [Input an entity value](custom-functions-data-types-concepts.md#input-an-entity-value). + ### Matrix type Use a two-dimensional array type to have the parameter or return value be a matrix of values. For example, the type `number[][]` indicates a matrix of numbers and `string[][]` indicates a matrix of strings. diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index 6a983bc272..1488a579c9 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -142,6 +142,8 @@ The `allowCustomDataForDataTypeAny` property is a boolean data type. Setting thi > [!NOTE] > Unlike most of the other JSON metadata properties, `allowCustomDataForDataTypeAny` is a top-level property and contains no sub-properties. See the preceding [JSON metadata code sample](#json-metadata-example) for an example of how to format this property. +If your custom function uses the `cellValueType` [parameter](#parameters), then setting the `allowCustomDataForDataTypeAny` is not required to accept data types as parameters and return values. + ### allowErrorForDataTypeAny The `allowErrorForDataTypeAny` property is a boolean data type. Setting the value to `true` allows a custom function to process errors as input values. All parameters with the type `any` or `any[][]` can accept errors as input values when `allowErrorForDataTypeAny` is set to `true`. The default `allowErrorForDataTypeAny` value is `false`. @@ -197,7 +199,7 @@ The `parameters` property is an array of parameter objects. The following table > "name": "range", > "description": "the input range", > "type": "any", /* A `type` value of `any` is required to use the `cellValueType` sub-field. */ -> "cellValueType": "??" +> "cellValueType": "webimagecellvalue" > } > ] > ``` From 27d1032bac85baafc576a9032010ab35bd9e5836 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 18 Oct 2024 16:48:17 -0700 Subject: [PATCH 7/7] Grammar changes --- docs/excel/custom-functions-json.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/excel/custom-functions-json.md b/docs/excel/custom-functions-json.md index 1488a579c9..de094d4a95 100644 --- a/docs/excel/custom-functions-json.md +++ b/docs/excel/custom-functions-json.md @@ -142,7 +142,7 @@ The `allowCustomDataForDataTypeAny` property is a boolean data type. Setting thi > [!NOTE] > Unlike most of the other JSON metadata properties, `allowCustomDataForDataTypeAny` is a top-level property and contains no sub-properties. See the preceding [JSON metadata code sample](#json-metadata-example) for an example of how to format this property. -If your custom function uses the `cellValueType` [parameter](#parameters), then setting the `allowCustomDataForDataTypeAny` is not required to accept data types as parameters and return values. +If your custom function uses the `cellValueType` [parameter](#parameters), then setting the `allowCustomDataForDataTypeAny` isn't required to accept data types as parameters and return values. ### allowErrorForDataTypeAny @@ -192,13 +192,13 @@ The `parameters` property is an array of parameter objects. The following table |`repeating`| boolean | No | If `true`, parameters populate from a specified array. Note that functions all repeating parameters are considered optional parameters by definition. | > [!TIP] -> See the following code snippet for an example of how to format the `cellValueType` parameter. +> See the following code snippet for an example of how to format the `cellValueType` parameter in JSON metadata. > ```json > "parameters": [ > { > "name": "range", > "description": "the input range", -> "type": "any", /* A `type` value of `any` is required to use the `cellValueType` sub-field. */ +> "type": "any", > "cellValueType": "webimagecellvalue" > } > ]