|
| 1 | +--- |
| 2 | +page_type: sample |
| 3 | +products: |
| 4 | +- office-excel |
| 5 | +- office-365 |
| 6 | +languages: |
| 7 | +- typescript |
| 8 | +extensions: |
| 9 | + contentType: samples |
| 10 | + technologies: |
| 11 | + - Add-ins |
| 12 | + createdDate: 3/02/2020 1:25:00 PM |
| 13 | +description: "This sample shows how to create contextual ribbon buttons that are enabled based on the state of your add-in. It also shows how to use the Office.js API to show or hide the task pane. This sample also demonstrates how to run code when the task pane is closed, such as on document open." |
| 14 | +--- |
| 15 | + |
| 16 | +# Manage ribbon and task pane UI, and run code on doc open |
| 17 | + |
| 18 | +## Summary |
| 19 | + |
| 20 | +This sample shows how to create contextual ribbon buttons that are enabled based on the state of your add-in. It also shows how to use the Office.js API to show or hide the task pane. This sample also demonstrates how to run code when the task pane is closed, such as on document open. |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +## Features |
| 25 | + |
| 26 | +- Contextual ribbon UI that enables or disables the buttons. |
| 27 | +- Set load behavior to load the add-in and run code when the document is opened. |
| 28 | +- Open and close the task pane through the Office.js API. |
| 29 | +- Handle Office.js events even when the task pane is closed. |
| 30 | +- Share data globally, such as between custom functions and the task pane. |
| 31 | + |
| 32 | +## Applies to |
| 33 | + |
| 34 | +- Excel on Windows (one-time purchase and subscription) |
| 35 | + |
| 36 | +## Prerequisites |
| 37 | + |
| 38 | +The features used in this sample are currently in preview and subject to change. They are not currently supported for use in production environments. To try the preview features, you will need to [join Office Insider](https://insider.office.com/join). A good way to try out preview features is by using an Office 365 subscription. If you don't already have an Office 365 subscription, you can get one by joining the [Office 365 Developer Program](https://developer.microsoft.com/office/dev-program). |
| 39 | + |
| 40 | +Before running this sample, make sure you have installed a recent version of [npm](https://www.npmjs.com/get-npm) and [Node.js](https://nodejs.org/en/) on your computer. To check if you have already installed these tools, run the commands `node -v` and `npm -v` in your terminal. |
| 41 | + |
| 42 | +## Solution |
| 43 | + |
| 44 | +Solution | Author(s) |
| 45 | +---------|---------- |
| 46 | +Office Add-in Shared Runtime Ribbon/Task pane APIs | Microsoft |
| 47 | + |
| 48 | +## Version history |
| 49 | + |
| 50 | +Version | Date | Comments |
| 51 | +---------| -----| -------- |
| 52 | +1.0 | 3-2-2020 | Initial release |
| 53 | + |
| 54 | +## Disclaimer |
| 55 | + |
| 56 | +**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.** |
| 57 | + |
| 58 | +---------- |
| 59 | + |
| 60 | +## Scenario: A contextual add-in |
| 61 | + |
| 62 | +This sample demonstrates a fictional scenario where the add-in connects to a backend data service to help the user import and work with Contoso data. To keep things simple, the data is mock data and the sample does not require an actual backend data service. |
| 63 | + |
| 64 | +The add-in is aware of whether it is connected. When connected you will see the task pane update to allow you to import data, and also the ribbon buttons will be enabled to let you insert a table and work with the data. |
| 65 | + |
| 66 | +Additionally the add-in has a custom function that can display a filtered view of the data. The custom function is aware of the connection status, so that when connected, it will display the mock data. When disconnected, it will show `#N/A`. |
| 67 | + |
| 68 | +## Build and run the solution |
| 69 | + |
| 70 | +In the command prompt, run the command `start npm start`. This will open a second command prompt, build the project and then start a server (with dev mode settings). It takes from 5 to 30 seconds. When it finishes, the last line should say `Compiled successfully`. Minimize this command prompt. |
| 71 | + |
| 72 | +Back in the original command prompt, run the command `npm run sideload`. This will launch Excel and sideload the add-in. After a few seconds, a ribbon named `Contoso Data` will appear. |
| 73 | + |
| 74 | +The add-in's ribbon buttons have the following behavior: |
| 75 | + |
| 76 | +- **Connect service:** Connects to a mock Contoso data service. You can choose a CSV file, or database. |
| 77 | +- **Disconnect service:** Disonnects from the mock Contoso data service. |
| 78 | +- **Insert data:** Inserts a table from the mock Contoso data service. |
| 79 | +- **Sum:** Enabled when you are in the table. Select a range of numerical cells and it will output the sum of those cells. |
| 80 | +- **Load on doc open:** Choose this to enable the add-in to run the next time the document is opened. The `Sum` button will work immediately when in the table the next time the document is opened. Note that you need to save the document first to save this change. |
| 81 | +- **No load behavior:** Choose this to disable the add-in from running on document open. The Sum button will not work until you activate the add-in in some way (ribbon, task pane or custom function action). |
| 82 | +- **Open task pane:** Opens the task pane. |
| 83 | +- **Close task pane:** Closes the task pane. The task pane is not shut down and will remember its state. |
| 84 | + |
| 85 | +If the add-in is not connected to a service, the task pane will show a button to connect. Once connected, the task pane lets you choose a category from the data and insert a custom function. The custom function will filter data displayed to the selected category. |
| 86 | + |
| 87 | + |
| 88 | +## Key parts of this sample |
| 89 | + |
| 90 | +Global state is tracked in a window object retrieved using a `getGlobal()` function. This is accessible to custom functions, the task pane, and the ribbon (because all the code is running in the same JavaScript runtime.) The `ensureStateInitialized()` method initializes global state on startup. The global state tracks many items such as whether the add-in is connected to a service, and whether the task pane is open or closed. |
| 91 | + |
| 92 | +### Enable and disable ribbon buttons |
| 93 | + |
| 94 | +To enable and disable ribbon buttons the add-in uses the `Office.ribbon.requestUpdate` method and passes a JSON description of the buttons. Anytime there is a state change that requires the ribbon buttons to change, the `updateRibbon()` is called which sets if buttons are enabled based on global state variables. |
| 95 | + |
| 96 | +### Open and close the task pane |
| 97 | + |
| 98 | +To open or close the task pane, the add-in uses the `Office.addin.showAsTaskpane()` and `Office.addin.hide()` methods. |
| 99 | + |
| 100 | +### Set runtime load behavior |
| 101 | + |
| 102 | +If the `Load on doc open` button is chosen, the add-in configures the document so that the add-in begins running as soon as the document is opened. This allows the add-in to start running and monitoring Office events before the task pane is displayed. To configure the document to load the add-in on open, the add-in uses the `Office.addin.setStartupBehavior(Office.StartupBehavior.load)` method. To turn off the document load behavior, the add-in uses the `Office.addin.setStartupBehavior(Office.StartupBehavior.none)` method. |
| 103 | + |
| 104 | +### Run code in the background |
| 105 | + |
| 106 | +The add-in has a `Sum` button that is enabled when you move the range selection inside the expenses table. An event in the table is used to detect when the range selection is in or out of the table. If the add-in was configured to load on doc open, the event code will be operational as soon as the document is opened, and the `Sum` button will work even though the task pane is not yet opened. |
| 107 | + |
| 108 | +To run code when the document opens, the add-in relies on the `Office.Initialize` event. This event is called when the document is opened and the load behavior is set for doc open. The add-in calls `ensureInitialize()` to set up the initial global state. |
| 109 | + |
| 110 | +```typescript |
| 111 | +Office.initialize = async () => { |
| 112 | + ensureStateInitialized(true); |
| 113 | + |
| 114 | + ... |
| 115 | +``` |
| 116 | +
|
| 117 | +The `ensureStateInitialized()` method will call the `monitorSheetCHanges()` method which will then search for the expenses table. If the expenses table was inserted, it adds an event handler for the `onTableSelectionChange` event. This is how the event handler code is set up on doc open. |
| 118 | +
|
| 119 | +```typescript |
| 120 | +export async function monitorSheetChanges() { |
| 121 | + try { |
| 122 | + let g = getGlobal() as any; |
| 123 | + if (g.state.isInitialized) { |
| 124 | + await Excel.run(async context => { |
| 125 | + let table = context.workbook.tables.getItem('ExpensesTable'); |
| 126 | + if (table !== undefined) { |
| 127 | + table.onSelectionChanged.add(onTableSelectionChange); |
| 128 | + await context.sync(); |
| 129 | + updateRibbon(); |
| 130 | + } else { |
| 131 | + g.state.isSumEnabled = false; |
| 132 | + updateRibbon(); |
| 133 | + } |
| 134 | + ... |
| 135 | +``` |
| 136 | +
|
| 137 | +## Security notes |
| 138 | +
|
| 139 | +In the webpack.dev.js file, a header is set to `"Access-Control-Allow-Origin": "*"`. This is only for development purposes. In production code, you should list the allowed domains and not leave this header open to all domains. |
| 140 | +
|
| 141 | +You'll be prompted to install certificates for trusted access to https://localhost. The certificates are intended only for running and studying this code sample. Do not reuse them in your own code solutions or in production environments. |
| 142 | +
|
| 143 | +You can install or uninstall the certificates by running the following commands in the project folder. |
| 144 | +
|
| 145 | +``` |
| 146 | +npx office-addin-dev-certs install |
| 147 | +npx office-addin-dev-certs uninstall |
| 148 | +``` |
| 149 | +
|
| 150 | +## Copyright |
| 151 | +
|
| 152 | +Copyright (c) 2020 Microsoft Corporation. All rights reserved. |
| 153 | +
|
| 154 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
| 155 | +
|
| 156 | +<img src="https://telemetry.sharepointpnp.com/officedev/samples/excel-shared-runtime-scenario" /> |
0 commit comments