diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index 72c17f689..f7b030cd3 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -40,6 +40,11 @@ In this tutorial, you'll create an Excel task pane add-in that: ![The Yeoman Office Add-in generator command line interface.](../images/yo-office-excel.png) +Next, select the type of manifest that you'd like to use, either the **unified manifest for Microsoft 365** or the **add-in only manifest**. Most of the steps in this tutorial are the same regardless of the manifest type, but the [Protect a worksheet](#protect-a-worksheet) section has separate steps for each manifest type. + +> [!NOTE] +> Using the unified manifest for Microsoft 365 with Excel add-ins is in public developer preview. The unified manifest for Microsoft 365 shouldn't be used in production Excel add-ins. We invite you to try it out in test or development environments. For more information, see the [Public developer preview app manifest schema](/microsoftteams/platform/resources/schema/manifest-schema-dev-preview). + After you complete the wizard, the generator creates the project and installs supporting Node components. You may need to manually run `npm install` in the root folder of your project if something fails during the initial setup. ## Create a table @@ -475,16 +480,114 @@ In this step of the tutorial, you'll add a button to the ribbon that toggles wor ### Configure the manifest to add a second ribbon button -There are two manifest options for Office Add-ins: the unified manifest for Microsoft 365, and the add-in only manifest. +The steps vary depending on the type of manifest. -# [Unified manifest for Microsoft 365](#tab/jsonmanifest) +# [Unified manifest for Microsoft 365 (preview)](#tab/jsonmanifest) > [!NOTE] -> The unified manifest for Microsoft 365 is currently in public developer preview for Excel and shouldn't be used in production Excel add-ins. We invite you to try it out in test or development environments. Use the add-in only manifest for production Excel add-ins. +> Using the unified manifest for Microsoft 365 with Excel add-ins is in public developer preview. The unified manifest for Microsoft 365 shouldn't be used in production Excel add-ins. We invite you to try it out in test or development environments. For more information, see the [Public developer preview app manifest schema](/microsoftteams/platform/resources/schema/manifest-schema-dev-preview). + +#### Configure the runtime for the ribbon button 1. Open the manifest file **./manifest.json**. -1. (More steps TBD) +1. Find the **"extensions.runtimes"** array and add the following commands runtime object. + + ```json + "runtimes": [ + { + "id": "CommandsRuntime", + "type": "general", + "code": { + "page": "https://localhost:3000/commands.html" + }, + "lifetime": "short", + "actions": [ + { + "id": , + "type": "executeFunction", + } + ] + } + ] + ``` + +1. Find `TODO1` and replace it with **"toggleProtection"**. This matches the `id` for the JavaScript function you create in a later step. + + > [!TIP] + > The value of **"actions.id"** must match the first parameter of the call to `Office.actions.associate` in your **commands.js** file. + +1. Ensure that the **"requirements.capabilities"** array contains an object that specifies the **"AddinCommands"** requirement set with a **"minVersion"** of **"1.1"**. + + ```json + "requirements": { + "capabilities": [ + { + "name": "AddinCommands", + "minVersion": "1.1" + } + ] + }, + ``` + +#### Configure the UI for the ribbon button + +1. After the **"extensions.runtimes"** array, add the following **"ribbons"** array. + + ```json + "ribbons": [ + { + "contexts": [ + "default" + ], + "tabs": [ + { + "builtInTabID": , + "groups": [ + { + "id": "worksheetProtectionGroup", + "label": "Contoso Add-in", + "controls": [ + { + "id": "toggleProtectionButton", + "type": "button", + "label": , + "icons": [ + { + "size": 16, + "url": "https://localhost:3000/assets/icon-16.png" + }, + { + "size": 32, + "url": "https://localhost:3000/assets/icon-32.png" + }, + { + "size": 80, + "url": "https://localhost:3000/assets/icon-80.png" + } + ], + "supertip": { + "title": "Toggle worksheet protection", + "description": "Enables or disables worksheet protection." + }, + "actionId": + } + ] + } + ] + } + ] + } + ] + ``` + +1. Find `TODO1` and replace it with **"TabHome"**. This ensures that the new button displays in the Home tab in Excel. For other available tab IDs, see [Find the IDs of built-in Office ribbon tabs](/develop/built-in-ui-ids.md). + +1. Find `TODO2` and replace it with **"Toggle worksheet protection"**. This is the label for your button in the Excel ribbon. + +1. Find `TODO3` and replace it with **"toggleProtection"**. This value must match the **"runtimes.actions.id"** value. + +1. Save the file. # [Add-in only manifest](#tab/xmlmanifest) @@ -582,6 +685,8 @@ There are two manifest options for Office Add-ins: the unified manifest for Micr 1. Save the file. +--- + ### Create the function that protects the sheet 1. Open the file **.\commands\commands.js**.