[Excel] (Custom Functions) Add new Get started article #4852
Conversation
|
Learn Build status updates of commit 712e066: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Learn Build status updates of commit ff08ae3: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
|
Thank you @alison-mk for putting things together and I've reviewed and approved it! |
|
Learn Build status updates of commit 90adaef: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
| @@ -0,0 +1,112 @@ | |||
| --- | |||
| description: Get started with Excel custom functions for Office Add-ins. | |||
| title: Get started with custom functions in Excel | |||
There was a problem hiding this comment.
| title: Get started with custom functions in Excel | |
| title: Best practices for custom functions in Excel |
There was a problem hiding this comment.
Do you recommend changing the title throughout (the H1 in the article, the TOC name), or only here?
|
|
||
| An **external service** is optional. It can give your add-in capabilities like importing data from outside the workbook. The custom functions add-in specifies how external data is incorporated into the workbook. To learn more, see [Receive and handle data with custom functions](custom-functions-web-reqs.md). | ||
|
|
||
| To develop a custom functions add-in with high performance, it’s important to ensure that these three components operate in harmony. |
There was a problem hiding this comment.
I don't know that this sentence is informative. Delete?
| #### Option 1: Less nesting | ||
|
|
||
| ```js | ||
| /** |
There was a problem hiding this comment.
How does this nest another custom function? I can call this with Add(1,2,3) (no custom functions).
There was a problem hiding this comment.
@grangeryy Can you answer David's question here?
| } | ||
| ``` | ||
|
|
||
| #### Option 2: More nesting |
There was a problem hiding this comment.
If this is the "bad" example, might be better to start with this, explain why it causes extra calc, and then show the better example. right now it looks like you can use either option equally well.
|
|
||
| ### Excel calculation mode | ||
|
|
||
| Excel has three calculation modes: Automatic, Automatic Except Tables, and Manual. For a description of these calculation modes, see [Excel Recalculation](/office/client-developer/excel/excel-recalculation). The most frequently used calculation mode for custom functions add-ins is manual calculation mode. Set the calculation mode for your add-in with the [Excel.CalculationMode enum](/javascript/api/excel/excel.calculationmode) based on your scenario. Note that automatic calculation mode may trigger recalculation often and reduce the efficiency of your add-in. |
There was a problem hiding this comment.
Might make a clearer call to action here if the goal is to make your custom functions more efficient by reading the article. Perhaps the goal is to "Refer to the article and determine which calculation mode will work best for your custom function design..."
|
|
||
| To return multiple results with one function, use a dynamic array. This is usually the recommended approach because dynamic arrays only require updating a single cell to trigger recalculation for all results. To learn more about dynamic arrays in custom functions, see [Return multiple results from your custom function](custom-functions-dynamic-arrays.md). | ||
|
|
||
| Another way to return multiple results is to use multiple functions and return a single result for each function. A benefit of using multiple functions is that your end user can decide precisely which formula they want to update and then only trigger recalculation for that formula. |
There was a problem hiding this comment.
Might be good to show example like in the spec. Also point out the tradeoff of how one function for multiple results is less efficient across a larger dataset. Especially if relying on an external service.
|
|
||
| Another way to return multiple results is to use multiple functions and return a single result for each function. A benefit of using multiple functions is that your end user can decide precisely which formula they want to update and then only trigger recalculation for that formula. | ||
|
|
||
| ### Complex data structures |
There was a problem hiding this comment.
I'm unclear on how the subsections here related to complex data structures. They look like they apply to basic data types as well.
There was a problem hiding this comment.
My thinking is that all Excel data types are a "complex data structure" from the perspective of custom functions, and the goal of this section is the communicate that data types offer a way for custom functions to handle complex data structures.
|
|
||
| ## Improve the user experience of remote data calls | ||
|
|
||
| Custom functions can fetch data from remote locations beyond the workbook, such as the web or a server. For more information about fetching remote data, see [Receive and handle data with custom functions](custom-functions-web-reqs.md). To maintain efficiency when making remote data calls, consider batching external calls, minimizing roundtrip duration for each call, and including messages in your add-in to communicate delays to your end user. |
There was a problem hiding this comment.
Would be good to use the term "external service" to tie in with the graphic at the beginning and connect the dots here.
| Remote service connections can have a large impact on custom function performance. To reduce this impact, use these strategies: | ||
|
|
||
| - Server-heavy processing should be handled efficiently in the remote server to shorten the end-to-end latency for a custom function. For example, have parallel computing designed on the server. If your service is deployed on Azure, consider optimization using [high-performance computing on Azure](/azure/architecture/topics/high-performance-computing). | ||
| - Reduce the number of service calls by optimizing the add-in flow. For example, only send necessary calls to a remote service. |
There was a problem hiding this comment.
I would image we could have another section about using a cache for repeat CF calls, or common calls. Check with Phoebe.
There was a problem hiding this comment.
@grangeryy Can you take a look at David's suggestion here?
|
|
||
| ### Improve user-perceived performance through add-in UX | ||
|
|
||
| If a delay while calling a remote service is inevitable, consider providing messages through the add-in task pane to explain the delay to your end users. This information helps manage their expectations. The following image shows an example. |
There was a problem hiding this comment.
I would mention that they will see the "busy" text in the cell while processing, so it's not like you should always think to use the task pane. But if you fell you must might be good to point out a pattern here of how it works. You need CF runtime, set the TP image on CF entry, then turn off the TP image on CF exit. Plus the task pane has to keep track if multiple CF long processes are running (which could get complicated).
No description provided.