adds synchronous custom function sample showing how to read a cell value using @SupportSync

Author: Pravandan Chand

playlists-prod/excel.yaml

@@ -1449,4 +1449,15 @@
     https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/99-just-for-fun/color-wheel.yaml
   group: Just For Fun
   api_set:
-    ExcelApi: '1.4'
+    ExcelApi: '1.4'
+- id: excel-custom-functions-sync
+  name: Synchronous custom function
+  fileName: synchronous-function.yaml
+  description: >-
+    A synchronous custom function that reads a cell value in tandem with Excel's
+    calculation process.
+  rawUrl: >-
+    https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/preview-apis/synchronous-function.yaml
+  group: Preview APIs
+  api_set:
+    CustomFunctionsRuntime: 1.5

playlists/excel.yaml

@@ -1450,3 +1450,14 @@
   group: Just For Fun
   api_set:
     ExcelApi: '1.4'
+- id: excel-custom-functions-sync
+  name: Synchronous custom function
+  fileName: synchronous-function.yaml
+  description: >-
+    A synchronous custom function that reads a cell value in tandem with Excel's
+    calculation process.
+  rawUrl: >-
+    https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/preview-apis/synchronous-function.yaml
+  group: Preview APIs
+  api_set:
+    CustomFunctionsRuntime: 1.5

samples/excel/preview-apis/synchronous-function.yaml

@@ -0,0 +1,29 @@
+order: 9
+id: excel-custom-functions-sync
+name: Synchronous custom function
+description: A synchronous custom function that reads a cell value in tandem with Excel's calculation process.
+host: EXCEL
+api_set:
+    CustomFunctionsRuntime: 1.5
+script:
+    content: |
+        /**
+         * Gets the value of a cell, evaluated synchronously with Excel's calculation.
+         * @customfunction
+         * @supportSync
+         * @param {string} address The cell address, e.g. "A1"
+         * @param {CustomFunctions.Invocation} invocation
+         * @returns {Promise<any>} The cell value.
+         */
+        async function getCellValue(address: string, invocation: CustomFunctions.Invocation): Promise<any> {
+          const context = new Excel.RequestContext();
+          context.setInvocation(invocation as any);
+          const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
+          range.load("values");
+          await context.sync();
+          return range.values[0][0];
+        }
+    language: typescript
+libraries: |
+    https://appsforoffice.microsoft.com/lib/beta/hosted/office.js
+    https://raw.githubusercontent.com/DefinitelyTyped/DefinitelyTyped/master/types/office-js-preview/index.d.ts

view-prod/excel.json

@@ -149,5 +149,6 @@
   "excel-just-for-fun-gradient": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/99-just-for-fun/gradient.yaml",
   "excel-just-for-fun-path-finder-game": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/99-just-for-fun/path-finder-game.yaml",
   "excel-just-for-fun-tetrominos": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/99-just-for-fun/tetrominos.yaml",
-  "excel-just-for-fun-color-wheel": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/99-just-for-fun/color-wheel.yaml"
+  "excel-just-for-fun-color-wheel": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/99-just-for-fun/color-wheel.yaml",
+  "excel-custom-functions-sync": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/preview-apis/synchronous-function.yaml"
 }

view/excel.json

@@ -149,5 +149,6 @@
   "excel-just-for-fun-gradient": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/99-just-for-fun/gradient.yaml",
   "excel-just-for-fun-path-finder-game": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/99-just-for-fun/path-finder-game.yaml",
   "excel-just-for-fun-tetrominos": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/99-just-for-fun/tetrominos.yaml",
-  "excel-just-for-fun-color-wheel": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/99-just-for-fun/color-wheel.yaml"
+  "excel-just-for-fun-color-wheel": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/99-just-for-fun/color-wheel.yaml",
+  "excel-custom-functions-sync": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/preview-apis/synchronous-function.yaml"
 }