Skip to content

Commit 65b4833

Browse files
alison-mkalison-mk
authored
[Excel] (Custom functions) Add invocation snippets (#2263)
* [Excel] (Custom functions) Add invocation snippets * Run generate docs after adding custom functions snippets * Fix adjustment * Incorporate feedback and run generate docs
1 parent 6c6559d commit 65b4833

File tree

59 files changed

+2425
-61
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

59 files changed

+2425
-61
lines changed

‎docs/code-snippets/custom-functions-snippets.yaml

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,73 @@ CustomFunctions.ErrorCode:enum:
4949
// Return the results of the first and third parameter calculations
5050
// and a #NUM! error in place of the second result.
5151
return [[firstResult], [secondResult], [thirdResult]];
52-
};
52+
};
53+
CustomFunctions.Invocation:interface:
54+
- |-
55+
/**
56+
* Return the address of the cell that invoked the custom function.
57+
* @customfunction
58+
* @param {number} first First parameter.
59+
* @param {number} second Second parameter.
60+
* @param {CustomFunctions.Invocation} invocation Invocation object.
61+
* @requiresAddress
62+
*/
63+
function getAddress(first, second, invocation) {
64+
const address = invocation.address;
65+
return address;
66+
}
67+
CustomFunctions.Invocation#address:member:
68+
- |-
69+
/**
70+
* Return the address of the cell that invoked the custom function.
71+
* @customfunction
72+
* @param {number} first First parameter.
73+
* @param {number} second Second parameter.
74+
* @param {CustomFunctions.Invocation} invocation Invocation object.
75+
* @requiresAddress
76+
*/
77+
function getAddress(first, second, invocation) {
78+
const address = invocation.address;
79+
return address;
80+
}
81+
CustomFunctions.Invocation#isInValuePreview:member:
82+
- |-
83+
/**
84+
* Get the listing price for a house on the market for the given address.
85+
* @customfunction
86+
* @param address The address of the house.
87+
* @param invocation Custom function handler.
88+
* @returns The price of the house at the address.
89+
*/
90+
function getHousePrice(address: string, invocation: CustomFunctions.Invocation): number {
91+
// Check if this call is for formula value preview mode.
92+
if (invocation.isInValuePreview) {
93+
// Avoid long-running expensive service calls.
94+
// Return a usable but fake number.
95+
return 450000;
96+
} else {
97+
// Make the actual service calls in this block.
98+
const price = callHouseServiceAPI(address);
99+
return price;
100+
}
101+
}
102+
CustomFunctions.Invocation#parameterAddresses:member:
103+
- |-
104+
/**
105+
* Return the addresses of three parameters.
106+
* @customfunction
107+
* @param {string} firstParameter First parameter.
108+
* @param {string} secondParameter Second parameter.
109+
* @param {string} thirdParameter Third parameter.
110+
* @param {CustomFunctions.Invocation} invocation Invocation object.
111+
* @returns {string[][]} The addresses of the parameters, as a 2-dimensional array.
112+
* @requiresParameterAddresses
113+
*/
114+
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
115+
const addresses = [
116+
[invocation.parameterAddresses[0]],
117+
[invocation.parameterAddresses[1]],
118+
[invocation.parameterAddresses[2]]
119+
];
120+
return addresses;
121+
}

‎docs/docs-ref-autogen/excel/custom-functions-runtime/customfunctions.invocation.yml

Lines changed: 123 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,25 @@ uid: custom-functions-runtime!CustomFunctions.Invocation:interface
44
package: custom-functions-runtime!
55
fullName: CustomFunctions.Invocation
66
summary: Provides information about the invocation of a custom function.
7-
remarks: ''
7+
remarks: |-
8+
9+
10+
#### Examples
11+
12+
```TypeScript
13+
/**
14+
* Return the address of the cell that invoked the custom function.
15+
* @customfunction
16+
* @param {number} first First parameter.
17+
* @param {number} second Second parameter.
18+
* @param {CustomFunctions.Invocation} invocation Invocation object.
19+
* @requiresAddress
20+
*/
21+
function getAddress(first, second, invocation) {
22+
const address = invocation.address;
23+
return address;
24+
}
25+
```
826
927
isPreview: false
1028
isDeprecated: false
@@ -30,6 +48,35 @@ properties:
3048
1.1](/javascript/api/requirement-sets/excel/custom-functions-requirement-sets)
3149
\]
3250
51+
52+
#### Examples
53+
54+
55+
```TypeScript
56+
57+
/**
58+
59+
* Return the address of the cell that invoked the custom function.
60+
61+
* @customfunction
62+
63+
* @param {number} first First parameter.
64+
65+
* @param {number} second Second parameter.
66+
67+
* @param {CustomFunctions.Invocation} invocation Invocation object.
68+
69+
* @requiresAddress
70+
71+
*/
72+
73+
function getAddress(first, second, invocation) {
74+
const address = invocation.address;
75+
return address;
76+
}
77+
78+
```
79+
3380
isPreview: false
3481
isDeprecated: false
3582
syntax:
@@ -67,6 +114,42 @@ properties:
67114
1.5](/javascript/api/requirement-sets/excel/custom-functions-requirement-sets)
68115
\]
69116
117+
118+
#### Examples
119+
120+
121+
```TypeScript
122+
123+
/**
124+
125+
* Get the listing price for a house on the market for the given address.
126+
127+
* @customfunction
128+
129+
* @param address The address of the house.
130+
131+
* @param invocation Custom function handler.
132+
133+
* @returns The price of the house at the address.
134+
135+
*/
136+
137+
function getHousePrice(address: string, invocation:
138+
CustomFunctions.Invocation): number {
139+
// Check if this call is for formula value preview mode.
140+
if (invocation.isInValuePreview) {
141+
// Avoid long-running expensive service calls.
142+
// Return a usable but fake number.
143+
return 450000;
144+
} else {
145+
// Make the actual service calls in this block.
146+
const price = callHouseServiceAPI(address);
147+
return price;
148+
}
149+
}
150+
151+
```
152+
70153
isPreview: false
71154
isDeprecated: false
72155
syntax:
@@ -95,6 +178,45 @@ properties:
95178
1.3](/javascript/api/requirement-sets/excel/custom-functions-requirement-sets)
96179
\]
97180
181+
182+
#### Examples
183+
184+
185+
```TypeScript
186+
187+
/**
188+
189+
* Return the addresses of three parameters.
190+
191+
* @customfunction
192+
193+
* @param {string} firstParameter First parameter.
194+
195+
* @param {string} secondParameter Second parameter.
196+
197+
* @param {string} thirdParameter Third parameter.
198+
199+
* @param {CustomFunctions.Invocation} invocation Invocation object.
200+
201+
* @returns {string[][]} The addresses of the parameters, as a
202+
2-dimensional array.
203+
204+
* @requiresParameterAddresses
205+
206+
*/
207+
208+
function getParameterAddresses(firstParameter, secondParameter,
209+
thirdParameter, invocation) {
210+
const addresses = [
211+
[invocation.parameterAddresses[0]],
212+
[invocation.parameterAddresses[1]],
213+
[invocation.parameterAddresses[2]]
214+
];
215+
return addresses;
216+
}
217+
218+
```
219+
98220
isPreview: false
99221
isDeprecated: false
100222
syntax:

‎docs/docs-ref-autogen/excel/excel/excel.cardlayout.yml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,16 @@ uid: excel!Excel.CardLayout:type
44
package: excel!
55
fullName: Excel.CardLayout
66
summary: Represents the layout of a card in card view.
7-
remarks: "\\[ [API set: ExcelApi 1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \\]\r\n\r\nLearn more about the types in this type alias through the following links: \r\n\r\n[Excel.EntityCardLayout](/javascript/api/excel/excel.entitycardlayout), [Excel.EntityArrayCardLayout](/javascript/api/excel/excel.entityarraycardlayout)"
7+
remarks: >-
8+
\[ [API set: ExcelApi
9+
1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
10+
11+
12+
Learn more about the types in this type alias through the following links:
13+
14+
15+
[Excel.EntityCardLayout](/javascript/api/excel/excel.entitycardlayout),
16+
[Excel.EntityArrayCardLayout](/javascript/api/excel/excel.entityarraycardlayout)
817
918
isPreview: false
1019
isDeprecated: false

‎docs/docs-ref-autogen/excel/excel/excel.cardlayoutsection.yml

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,17 @@ uid: excel!Excel.CardLayoutSection:type
44
package: excel!
55
fullName: Excel.CardLayoutSection
66
summary: Represents the layout of a section of a card in card view.
7-
remarks: "\\[ [API set: ExcelApi 1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \\]\r\n\r\nLearn more about the types in this type alias through the following links: \r\n\r\n[Excel.CardLayoutListSection](/javascript/api/excel/excel.cardlayoutlistsection), [Excel.CardLayoutTableSection](/javascript/api/excel/excel.cardlayouttablesection), [Excel.CardLayoutTwoColumnSection](/javascript/api/excel/excel.cardlayouttwocolumnsection)"
7+
remarks: >-
8+
\[ [API set: ExcelApi
9+
1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
10+
11+
12+
Learn more about the types in this type alias through the following links:
13+
14+
15+
[Excel.CardLayoutListSection](/javascript/api/excel/excel.cardlayoutlistsection),
16+
[Excel.CardLayoutTableSection](/javascript/api/excel/excel.cardlayouttablesection),
17+
[Excel.CardLayoutTwoColumnSection](/javascript/api/excel/excel.cardlayouttwocolumnsection)
818
919
isPreview: false
1020
isDeprecated: false

‎docs/docs-ref-autogen/excel/excel/excel.cellcontrol.yml

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,45 @@ uid: excel!Excel.CellControl:type
44
package: excel!
55
fullName: Excel.CellControl
66
summary: Represents an interactable control inside of a cell.
7-
remarks: "\\[ [API set: ExcelApi 1.18](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \\]\n\n#### Examples\n\n```TypeScript\n// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml\n\n// Add checkboxes to the table.\nawait Excel.run(async (context) => {\n const sheet = context.workbook.worksheets.getActiveWorksheet();\n\n // Get the second column in the table, without the header.\n const range = sheet.tables.getItem(\"FruitTable\").columns.getItem(\"Analysis\").getDataBodyRange();\n\n // Change the boolean values to checkboxes.\n range.control = {\n type: Excel.CellControlType.checkbox\n };\n await context.sync();\n});\n```\r\n\r\nLearn more about the types in this type alias through the following links: \r\n\r\n[Excel.UnknownCellControl](/javascript/api/excel/excel.unknowncellcontrol), [Excel.EmptyCellControl](/javascript/api/excel/excel.emptycellcontrol), [Excel.MixedCellControl](/javascript/api/excel/excel.mixedcellcontrol), [Excel.CheckboxCellControl](/javascript/api/excel/excel.checkboxcellcontrol)"
7+
remarks: >-
8+
\[ [API set: ExcelApi
9+
1.18](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
10+
11+
12+
#### Examples
13+
14+
15+
```TypeScript
16+
17+
// Link to full sample:
18+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-cell-control.yaml
19+
20+
21+
// Add checkboxes to the table.
22+
23+
await Excel.run(async (context) => {
24+
const sheet = context.workbook.worksheets.getActiveWorksheet();
25+
26+
// Get the second column in the table, without the header.
27+
const range = sheet.tables.getItem("FruitTable").columns.getItem("Analysis").getDataBodyRange();
28+
29+
// Change the boolean values to checkboxes.
30+
range.control = {
31+
type: Excel.CellControlType.checkbox
32+
};
33+
await context.sync();
34+
});
35+
36+
```
37+
38+
39+
Learn more about the types in this type alias through the following links:
40+
41+
42+
[Excel.UnknownCellControl](/javascript/api/excel/excel.unknowncellcontrol),
43+
[Excel.EmptyCellControl](/javascript/api/excel/excel.emptycellcontrol),
44+
[Excel.MixedCellControl](/javascript/api/excel/excel.mixedcellcontrol),
45+
[Excel.CheckboxCellControl](/javascript/api/excel/excel.checkboxcellcontrol)
846
947
isPreview: false
1048
isDeprecated: false

‎docs/docs-ref-autogen/excel/excel/excel.cellvalue.yml

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,30 @@ uid: excel!Excel.CellValue:type
44
package: excel!
55
fullName: Excel.CellValue
66
summary: Represents the value in a cell.
7-
remarks: "\\[ [API set: ExcelApi 1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \\]\r\n\r\nLearn more about the types in this type alias through the following links: \r\n\r\n[Excel.ArrayCellValue](/javascript/api/excel/excel.arraycellvalue), [Excel.BooleanCellValue](/javascript/api/excel/excel.booleancellvalue), [Excel.DoubleCellValue](/javascript/api/excel/excel.doublecellvalue), [Excel.EntityCellValue](/javascript/api/excel/excel.entitycellvalue), [Excel.EmptyCellValue](/javascript/api/excel/excel.emptycellvalue), [Excel.ErrorCellValue](/javascript/api/excel/excel.errorcellvalue), [Excel.ExternalCodeServiceObjectCellValue](/javascript/api/excel/excel.externalcodeserviceobjectcellvalue), [Excel.FormattedNumberCellValue](/javascript/api/excel/excel.formattednumbercellvalue), [Excel.FunctionCellValue](/javascript/api/excel/excel.functioncellvalue), [Excel.LinkedEntityCellValue](/javascript/api/excel/excel.linkedentitycellvalue), [Excel.LocalImageCellValue](/javascript/api/excel/excel.localimagecellvalue), [Excel.ReferenceCellValue](/javascript/api/excel/excel.referencecellvalue), [Excel.StringCellValue](/javascript/api/excel/excel.stringcellvalue), [Excel.ValueTypeNotAvailableCellValue](/javascript/api/excel/excel.valuetypenotavailablecellvalue), [Excel.WebImageCellValue](/javascript/api/excel/excel.webimagecellvalue), [Excel.CellValueExtraProperties](/javascript/api/excel/excel.cellvalueextraproperties)"
7+
remarks: >-
8+
\[ [API set: ExcelApi
9+
1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
10+
11+
12+
Learn more about the types in this type alias through the following links:
13+
14+
15+
[Excel.ArrayCellValue](/javascript/api/excel/excel.arraycellvalue),
16+
[Excel.BooleanCellValue](/javascript/api/excel/excel.booleancellvalue),
17+
[Excel.DoubleCellValue](/javascript/api/excel/excel.doublecellvalue),
18+
[Excel.EntityCellValue](/javascript/api/excel/excel.entitycellvalue),
19+
[Excel.EmptyCellValue](/javascript/api/excel/excel.emptycellvalue),
20+
[Excel.ErrorCellValue](/javascript/api/excel/excel.errorcellvalue),
21+
[Excel.ExternalCodeServiceObjectCellValue](/javascript/api/excel/excel.externalcodeserviceobjectcellvalue),
22+
[Excel.FormattedNumberCellValue](/javascript/api/excel/excel.formattednumbercellvalue),
23+
[Excel.FunctionCellValue](/javascript/api/excel/excel.functioncellvalue),
24+
[Excel.LinkedEntityCellValue](/javascript/api/excel/excel.linkedentitycellvalue),
25+
[Excel.LocalImageCellValue](/javascript/api/excel/excel.localimagecellvalue),
26+
[Excel.ReferenceCellValue](/javascript/api/excel/excel.referencecellvalue),
27+
[Excel.StringCellValue](/javascript/api/excel/excel.stringcellvalue),
28+
[Excel.ValueTypeNotAvailableCellValue](/javascript/api/excel/excel.valuetypenotavailablecellvalue),
29+
[Excel.WebImageCellValue](/javascript/api/excel/excel.webimagecellvalue),
30+
[Excel.CellValueExtraProperties](/javascript/api/excel/excel.cellvalueextraproperties)
831
932
isPreview: false
1033
isDeprecated: false

‎docs/docs-ref-autogen/excel/excel/excel.cellvalueandpropertymetadata.yml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,16 @@ fullName: Excel.CellValueAndPropertyMetadata
66
summary: >-
77
Represents the value and metadata of a property. The metadata applies to the
88
property (and not the value), but it is combined with the value in this type.
9-
remarks: "\\[ [API set: ExcelApi 1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \\]\r\n\r\nLearn more about the types in this type alias through the following links: \r\n\r\n[Excel.CellValue](/javascript/api/excel/excel.cellvalue), [Excel.EntityPropertyExtraProperties](/javascript/api/excel/excel.entitypropertyextraproperties)"
9+
remarks: >-
10+
\[ [API set: ExcelApi
11+
1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
12+
13+
14+
Learn more about the types in this type alias through the following links:
15+
16+
17+
[Excel.CellValue](/javascript/api/excel/excel.cellvalue),
18+
[Excel.EntityPropertyExtraProperties](/javascript/api/excel/excel.entitypropertyextraproperties)
1019
1120
isPreview: false
1221
isDeprecated: false

‎docs/docs-ref-autogen/excel/excel/excel.compactlayout.yml

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,15 @@ fullName: Excel.CompactLayout
66
summary: >-
77
Represents the layout used when there is limited space to represent the
88
entity.
9-
remarks: "\\[ [API set: ExcelApi 1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \\]\r\n\r\nLearn more about the types in this type alias through the following links: \r\n\r\n[Excel.EntityCompactLayout](/javascript/api/excel/excel.entitycompactlayout)"
9+
remarks: >-
10+
\[ [API set: ExcelApi
11+
1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
12+
13+
14+
Learn more about the types in this type alias through the following links:
15+
16+
17+
[Excel.EntityCompactLayout](/javascript/api/excel/excel.entitycompactlayout)
1018
1119
isPreview: false
1220
isDeprecated: false

‎docs/docs-ref-autogen/excel/excel/excel.entitypropertytype.yml

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,16 @@ uid: excel!Excel.EntityPropertyType:type
44
package: excel!
55
fullName: Excel.EntityPropertyType
66
summary: Represents the value of a property.
7-
remarks: "\\[ [API set: ExcelApi 1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \\]\r\n\r\nLearn more about the types in this type alias through the following links: \r\n\r\n[Excel.CellValueAndPropertyMetadata](/javascript/api/excel/excel.cellvalueandpropertymetadata), [Excel.CellValue](/javascript/api/excel/excel.cellvalue)"
7+
remarks: >-
8+
\[ [API set: ExcelApi
9+
1.16](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]
10+
11+
12+
Learn more about the types in this type alias through the following links:
13+
14+
15+
[Excel.CellValueAndPropertyMetadata](/javascript/api/excel/excel.cellvalueandpropertymetadata),
16+
[Excel.CellValue](/javascript/api/excel/excel.cellvalue)
817
918
isPreview: false
1019
isDeprecated: false

0 commit comments

Comments
 (0)