From d0a82f1d3bb18977a0201c48fd6983c06f85d94c Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Wed, 23 Oct 2024 13:48:30 -0700 Subject: [PATCH 1/8] [Excel] (Tutorial) Begin unified manifest updates --- docs/tutorials/excel-tutorial.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index 2b767eefc1..c7918ea8b5 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -1,7 +1,7 @@ --- title: Excel add-in tutorial description: Build an Excel add-in that creates, populates, filters, and sorts a table, creates a chart, freezes a table header, protects a worksheet, and opens a dialog. -ms.date: 10/03/2024 +ms.date: 10/23/2024 ms.service: excel #Customer intent: As a developer, I want to build a Excel add-in that can interact with content in a Excel document. ms.localizationpriority: high @@ -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] +> Creating an Excel add-in with the unified manifest for Microsoft 365 is in public developer preview. It shouldn't be used in production 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,6 +480,22 @@ 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 +The steps vary depending on the type of manifest. + +# [Unified manifest for Microsoft 365 (preview)](#tab/jsonmanifest) + +> [!NOTE] +> Creating an Excel add-in with the unified manifest for Microsoft 365 is in public developer preview. It shouldn't be used in production 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). + +1. Open the manifest file **/manifest.json**. + +1. Local the Control element... + +1. +1. + +# [Add-in only manifest](#tab/xmlmanifest) + 1. Open the manifest file **./manifest.xml**. 1. Locate the **\** element. This element defines the **Show Taskpane** button on the **Home** ribbon you have been using to launch the add-in. We're going to add a second button to the same group on the **Home** ribbon. In between the closing **\** tag and the closing **\** tag, add the following markup. From 7d48423eddccd7cec5edeca1105dd7f2d70a3f58 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Wed, 23 Oct 2024 15:30:11 -0700 Subject: [PATCH 2/8] Add JSON runtime section --- docs/tutorials/excel-tutorial.md | 40 +++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index c7918ea8b5..056c2a6379 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -487,12 +487,46 @@ The steps vary depending on the type of manifest. > [!NOTE] > Creating an Excel add-in with the unified manifest for Microsoft 365 is in public developer preview. It shouldn't be used in production 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. Local the Control element... +1. Find the **extensions.runtimes** array. + +1. Create an object in the **extensions.runtimes** array with an **id** value of **CommandsRuntime**. + +1. Add a **type** property with the value **general**. + +1. Add a **code.page** property to the object with the value **https://localhost:3000/commands.html**. This is the UI-less HTML page that loads your function file. + +1. Add a **lifetime** property with the value **short**. + +1. Add an **actions.type** property with the value **executeFunction**. + +1. Add an **actions.id** property with the value **ToggleProtection**. This matches the `id` for the JavaScript function you create in a later step. Your **runtimes** array should now look like this: + +```json +"runtimes": [ + { + "id": "CommandsRuntime", + "type": "general", + "code": { + "page": "https://localhost:3000/commands.html" + }, + "lifetime": "short", + "actions": [ + { + "id": "ToggleProtection", + "type": "executeFunction", + } + ] + } +] +``` + +1. Ensure that the **requirements.capabilities** array contains an object that specifies the **AddinCommands** requirement set with a **minValue** of **1.1**. -1. -1. +#### Configure the UI for the ribbon button # [Add-in only manifest](#tab/xmlmanifest) From 5d05792107b33de66653bcc6cfa74f49d2811cf3 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Wed, 23 Oct 2024 21:41:33 -0700 Subject: [PATCH 3/8] Add JSON section for ribbon button --- docs/tutorials/excel-tutorial.md | 80 +++++++++++++++++++++++++++++++- 1 file changed, 78 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index 056c2a6379..bdcc800c03 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -493,7 +493,7 @@ The steps vary depending on the type of manifest. 1. Find the **extensions.runtimes** array. -1. Create an object in the **extensions.runtimes** array with an **id** value of **CommandsRuntime**. +1. Add an object to the **extensions.runtimes** array with an **id** value of **CommandsRuntime**. 1. Add a **type** property with the value **general**. @@ -503,7 +503,7 @@ The steps vary depending on the type of manifest. 1. Add an **actions.type** property with the value **executeFunction**. -1. Add an **actions.id** property with the value **ToggleProtection**. This matches the `id` for the JavaScript function you create in a later step. Your **runtimes** array should now look like this: +1. Add an **actions.id** property with the value **ToggleProtection**. This matches the `id` for the JavaScript function you create in a later step. Your **runtimes** array should now look like this: ```json "runtimes": [ @@ -528,6 +528,82 @@ The steps vary depending on the type of manifest. #### Configure the UI for the ribbon button +1. After the **extensions.runtimes** object, add a **ribbons** array. + +1. Add an object with array properties named **contexts** and **tabs**, as shown in the following example. + +```json +"ribbons": [ + { + "contexts": [ + // child objects omitted + ], + "tabs": [ + // child objects omitted + ] + } +] +``` + +1. Add a **"builtInTabId"** property to the **"tabs"** array with the value **"TabHome"**. This ensures that the new button displays in the Home tab. + +```json +"tabs": [ + { + "builtInTabID": "TabDefault", + "groups": [ + { + // properties omitted + } + ] + } +] +``` + +1. Find the **"groups"** array and add an **"id"** property with the value **"worksheetProtectionGroup"**. + +1. Add a **"label"** property with the value **"Contoso Add-in"**. Your **"groups"** array should look like this: + +```json +"groups": [ + { + "id": "worksheetProtectionGroup", + "label": "Contoso Add-in", + "controls": [ + { + // properties omitted + } + ] + } +] +``` + +1. In the **"groups.controls"** array, add the following properties and values: + - **"id": "toggleProtectionButton"** + - **"type": "button"** + - **"label": "Toggle worksheet protection"** + +1. Add a **"supertip"** object to the **"groups.controls"** array with the following properties and values: + - **"title": "Toggle worksheet protection"** + - **"description": "Enables or disables worksheet protection."** + +1. Add an **""actionId"** property to the **"groups.controls"** array with the value **"ShowTaskPane"**. Your **"controls"** array should now look like this: + +```json +{ + "id": "toggleProtectionButton", + "type": "button", + "label": "Toggle worksheet protection", + "supertip": { + "title": "Toggle worksheet protection", + "description": "Enables or disables worksheet protection." + }, + "actionId": "ToggleProtection" // This must match the "runtimes.actions.id" value. +} +``` + +1. Save the file. + # [Add-in only manifest](#tab/xmlmanifest) 1. Open the manifest file **./manifest.xml**. From 450ba9db6ef854fba1fc2ea1bce4055aa75cab13 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Wed, 23 Oct 2024 21:50:21 -0700 Subject: [PATCH 4/8] Make formatting more consistent --- docs/tutorials/excel-tutorial.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index bdcc800c03..cacb38d4a9 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -485,25 +485,25 @@ The steps vary depending on the type of manifest. # [Unified manifest for Microsoft 365 (preview)](#tab/jsonmanifest) > [!NOTE] -> Creating an Excel add-in with the unified manifest for Microsoft 365 is in public developer preview. It shouldn't be used in production 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). +> Using the unified manifest for Microsoft 365 with Excel add-ins is in public developer preview. It 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. Find the **extensions.runtimes** array. +1. Find the **"extensions.runtimes"** array. -1. Add an object to the **extensions.runtimes** array with an **id** value of **CommandsRuntime**. +1. Add an object to the **"extensions.runtimes"** array with an **"id"** value of **"CommandsRuntime"**. -1. Add a **type** property with the value **general**. +1. Add a **"type"** property with the value **"general"**. -1. Add a **code.page** property to the object with the value **https://localhost:3000/commands.html**. This is the UI-less HTML page that loads your function file. +1. Add a **"code.page"** property to the object with the value **"https://localhost:3000/commands.html"**. This is the UI-less HTML page that loads your function file. -1. Add a **lifetime** property with the value **short**. +1. Add a **"lifetime"** property with the value **"short"**. -1. Add an **actions.type** property with the value **executeFunction**. +1. Add an **"actions.type"** property with the value **"executeFunction"**. -1. Add an **actions.id** property with the value **ToggleProtection**. This matches the `id` for the JavaScript function you create in a later step. Your **runtimes** array should now look like this: +1. Add an **"actions.id"** property with the value **"ToggleProtection"**. This matches the `id` for the JavaScript function you create in a later step. Your **"runtimes"** array should now look like this: ```json "runtimes": [ @@ -524,13 +524,13 @@ The steps vary depending on the type of manifest. ] ``` -1. Ensure that the **requirements.capabilities** array contains an object that specifies the **AddinCommands** requirement set with a **minValue** of **1.1**. +1. Ensure that the **"requirements.capabilities"** array contains an object that specifies the **"AddinCommands"** requirement set with a **"minValue"** of **"1.1"**. #### Configure the UI for the ribbon button -1. After the **extensions.runtimes** object, add a **ribbons** array. +1. After the **"extensions.runtimes"** object, add a **"ribbons"** array. -1. Add an object with array properties named **contexts** and **tabs**, as shown in the following example. +1. Add an object with array properties named **"contexts"** and **"tabs"**, as shown in the following example. ```json "ribbons": [ From 5a88a702ff12eb243d644094db1bdf2866a9e587 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Thu, 24 Oct 2024 17:04:01 -0700 Subject: [PATCH 5/8] Formatting adjustments and slight restructuring --- docs/tutorials/excel-tutorial.md | 183 ++++++++++++++++--------------- 1 file changed, 95 insertions(+), 88 deletions(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index cacb38d4a9..24667eb1de 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -43,7 +43,7 @@ In this tutorial, you'll create an Excel task pane add-in that: 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] -> Creating an Excel add-in with the unified manifest for Microsoft 365 is in public developer preview. It shouldn't be used in production 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). +> 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. @@ -485,98 +485,103 @@ The steps vary depending on the type of manifest. # [Unified manifest for Microsoft 365 (preview)](#tab/jsonmanifest) > [!NOTE] -> Using the unified manifest for Microsoft 365 with Excel add-ins is in public developer preview. It 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). +> 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. Open the manifest file **./manifest.json**. 1. Find the **"extensions.runtimes"** array. -1. Add an object to the **"extensions.runtimes"** array with an **"id"** value of **"CommandsRuntime"**. - -1. Add a **"type"** property with the value **"general"**. +1. Add an object to the **"extensions.runtimes"** array with the following properties and values: + - **"id"**: **"CommandsRuntime"** + - **"type"**: **"general"** + - **"lifetime"**: **"short"** 1. Add a **"code.page"** property to the object with the value **"https://localhost:3000/commands.html"**. This is the UI-less HTML page that loads your function file. -1. Add a **"lifetime"** property with the value **"short"**. - -1. Add an **"actions.type"** property with the value **"executeFunction"**. - -1. Add an **"actions.id"** property with the value **"ToggleProtection"**. This matches the `id` for the JavaScript function you create in a later step. Your **"runtimes"** array should now look like this: - -```json -"runtimes": [ - { - "id": "CommandsRuntime", - "type": "general", - "code": { - "page": "https://localhost:3000/commands.html" - }, - "lifetime": "short", - "actions": [ - { - "id": "ToggleProtection", - "type": "executeFunction", - } - ] - } -] -``` +1. Add an **"actions"** object with the following properties and values: + - **"id"**: **"ToggleProtection"**. This matches the `id` for the JavaScript function you create in a later step. + - **"type"**: **"executeFunction"** + + Your **"runtimes"** array should now look like this: + + ```json + "runtimes": [ + { + "id": "CommandsRuntime", + "type": "general", + "lifetime": "short", + "code": { + "page": "https://localhost:3000/commands.html" + }, + "actions": [ + { + "id": "ToggleProtection", + "type": "executeFunction", + } + ] + } + ] + ``` 1. Ensure that the **"requirements.capabilities"** array contains an object that specifies the **"AddinCommands"** requirement set with a **"minValue"** of **"1.1"**. #### Configure the UI for the ribbon button -1. After the **"extensions.runtimes"** object, add a **"ribbons"** array. +1. After the **"extensions.runtimes"** array, add a **"ribbons"** array. 1. Add an object with array properties named **"contexts"** and **"tabs"**, as shown in the following example. -```json -"ribbons": [ - { - "contexts": [ - // child objects omitted - ], - "tabs": [ - // child objects omitted - ] - } -] -``` - -1. Add a **"builtInTabId"** property to the **"tabs"** array with the value **"TabHome"**. This ensures that the new button displays in the Home tab. - -```json -"tabs": [ - { - "builtInTabID": "TabDefault", - "groups": [ - { - // properties omitted - } - ] - } -] -``` - -1. Find the **"groups"** array and add an **"id"** property with the value **"worksheetProtectionGroup"**. - -1. Add a **"label"** property with the value **"Contoso Add-in"**. Your **"groups"** array should look like this: - -```json -"groups": [ - { - "id": "worksheetProtectionGroup", - "label": "Contoso Add-in", - "controls": [ - { - // properties omitted - } - ] - } -] -``` + ```json + "ribbons": [ + { + "contexts": [ + // child objects omitted + ], + "tabs": [ + // child objects omitted + ] + } + ] + ``` + +1. Add a **"builtInTabId"** property to the **"tabs"** array with the value **"TabHome"**. This ensures that the new button displays in the Home tab in Excel. + +1. Add a **"groups"** array within the **"tabs"** array. The **"groups"** array should contain one object. Your **"tabs"** array should look like this: + + ```json + "tabs": [ + { + "builtInTabID": "TabHome", + "groups": [ + { + // properties omitted + } + ] + } + ] + ``` + +1. Go to the **"groups"** array and add an **"id"** property with the value **"worksheetProtectionGroup"**. + +1. Add a **"label"** property to the **"groups"** array with the value **"Contoso Add-in"**. + +1. Add a **"controls"** array within the **"tabs"** array. The **"controls"** array should contain one object. Your **"groups"** array should look like this: + + ```json + "groups": [ + { + "id": "worksheetProtectionGroup", + "label": "Contoso Add-in", + "controls": [ + { + // properties omitted + } + ] + } + ] + ``` 1. In the **"groups.controls"** array, add the following properties and values: - **"id": "toggleProtectionButton"** @@ -589,18 +594,20 @@ The steps vary depending on the type of manifest. 1. Add an **""actionId"** property to the **"groups.controls"** array with the value **"ShowTaskPane"**. Your **"controls"** array should now look like this: -```json -{ - "id": "toggleProtectionButton", - "type": "button", - "label": "Toggle worksheet protection", - "supertip": { - "title": "Toggle worksheet protection", - "description": "Enables or disables worksheet protection." - }, - "actionId": "ToggleProtection" // This must match the "runtimes.actions.id" value. -} -``` + ```json + "controls": [ + { + "id": "toggleProtectionButton", + "type": "button", + "label": "Toggle worksheet protection", + "supertip": { + "title": "Toggle worksheet protection", + "description": "Enables or disables worksheet protection." + }, + "actionId": "ToggleProtection" // This must match the "runtimes.actions.id" value. + } + ] + ``` 1. Save the file. From 444f9059d6c22d3430c6f2d5cb9d1f83efb3c01a Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Thu, 24 Oct 2024 17:15:25 -0700 Subject: [PATCH 6/8] Formatting fixes, typo fix --- docs/tutorials/excel-tutorial.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index 24667eb1de..a9abf626db 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -504,7 +504,7 @@ The steps vary depending on the type of manifest. - **"id"**: **"ToggleProtection"**. This matches the `id` for the JavaScript function you create in a later step. - **"type"**: **"executeFunction"** - Your **"runtimes"** array should now look like this: + The new object in your **"runtimes"** array should look like this: ```json "runtimes": [ @@ -563,11 +563,11 @@ The steps vary depending on the type of manifest. ] ``` -1. Go to the **"groups"** array and add an **"id"** property with the value **"worksheetProtectionGroup"**. +1. Go to the **"groups"** array and add the following properties and values: + - **"id"**: **"worksheetProtectionGroup"** + - **"label"**: **"Contoso Add-in"** -1. Add a **"label"** property to the **"groups"** array with the value **"Contoso Add-in"**. - -1. Add a **"controls"** array within the **"tabs"** array. The **"controls"** array should contain one object. Your **"groups"** array should look like this: +1. Add a **"controls"** array within the **"groups"** array. The **"controls"** array should contain one object. Your **"groups"** array should look like this: ```json "groups": [ @@ -604,11 +604,14 @@ The steps vary depending on the type of manifest. "title": "Toggle worksheet protection", "description": "Enables or disables worksheet protection." }, - "actionId": "ToggleProtection" // This must match the "runtimes.actions.id" value. + "actionId": "ToggleProtection" } ] ``` + > [!TIP] + > The **"controls.actionId"** value must match the **"runtimes.actions.id"** value. + 1. Save the file. # [Add-in only manifest](#tab/xmlmanifest) @@ -707,6 +710,8 @@ The steps vary depending on the type of manifest. 1. Save the file. +--- + ### Create the function that protects the sheet 1. Open the file **.\commands\commands.js**. From 06efec5e7b2b9956f152e670b5c036d04be4e16f Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Thu, 24 Oct 2024 17:56:37 -0700 Subject: [PATCH 7/8] Reformat to simplify steps --- docs/tutorials/excel-tutorial.md | 126 +++++++++++-------------------- 1 file changed, 45 insertions(+), 81 deletions(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index a9abf626db..cfa7301665 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -491,33 +491,20 @@ The steps vary depending on the type of manifest. 1. Open the manifest file **./manifest.json**. -1. Find the **"extensions.runtimes"** array. - -1. Add an object to the **"extensions.runtimes"** array with the following properties and values: - - **"id"**: **"CommandsRuntime"** - - **"type"**: **"general"** - - **"lifetime"**: **"short"** - -1. Add a **"code.page"** property to the object with the value **"https://localhost:3000/commands.html"**. This is the UI-less HTML page that loads your function file. - -1. Add an **"actions"** object with the following properties and values: - - **"id"**: **"ToggleProtection"**. This matches the `id` for the JavaScript function you create in a later step. - - **"type"**: **"executeFunction"** - - The new object in your **"runtimes"** array should look like this: +1. Find the **"extensions.runtimes"** array and add the following commands runtime object. ```json "runtimes": [ { "id": "CommandsRuntime", "type": "general", - "lifetime": "short", "code": { "page": "https://localhost:3000/commands.html" }, + "lifetime": "short", "actions": [ { - "id": "ToggleProtection", + "id": , "type": "executeFunction", } ] @@ -525,13 +512,16 @@ The steps vary depending on the type of manifest. ] ``` +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 **"minValue"** of **"1.1"**. #### Configure the UI for the ribbon button -1. After the **"extensions.runtimes"** array, add a **"ribbons"** array. - -1. Add an object with array properties named **"contexts"** and **"tabs"**, as shown in the following example. +1. After the **"extensions.runtimes"** array, add the following **"ribbons"** array. ```json "ribbons": [ @@ -540,77 +530,51 @@ The steps vary depending on the type of manifest. // child objects omitted ], "tabs": [ - // child objects omitted - ] - } - ] - ``` - -1. Add a **"builtInTabId"** property to the **"tabs"** array with the value **"TabHome"**. This ensures that the new button displays in the Home tab in Excel. - -1. Add a **"groups"** array within the **"tabs"** array. The **"groups"** array should contain one object. Your **"tabs"** array should look like this: - - ```json - "tabs": [ - { - "builtInTabID": "TabHome", - "groups": [ { - // properties omitted + "builtInTabID": , + "groups": [ + { + "id": "worksheetProtectionGroup", + "label": "Contoso Add-in", + "controls": [ + { + "id": "toggleProtectionButton", + "type": "button", + "label": "Toggle worksheet protection", + "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. Go to the **"groups"** array and add the following properties and values: - - **"id"**: **"worksheetProtectionGroup"** - - **"label"**: **"Contoso Add-in"** +1. ** ADD STEPS FOR CONTEXTS ** -1. Add a **"controls"** array within the **"groups"** array. The **"controls"** array should contain one object. Your **"groups"** array should look like this: +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). - ```json - "groups": [ - { - "id": "worksheetProtectionGroup", - "label": "Contoso Add-in", - "controls": [ - { - // properties omitted - } - ] - } - ] - ``` - -1. In the **"groups.controls"** array, add the following properties and values: - - **"id": "toggleProtectionButton"** - - **"type": "button"** - - **"label": "Toggle worksheet protection"** - -1. Add a **"supertip"** object to the **"groups.controls"** array with the following properties and values: - - **"title": "Toggle worksheet protection"** - - **"description": "Enables or disables worksheet protection."** - -1. Add an **""actionId"** property to the **"groups.controls"** array with the value **"ShowTaskPane"**. Your **"controls"** array should now look like this: - - ```json - "controls": [ - { - "id": "toggleProtectionButton", - "type": "button", - "label": "Toggle worksheet protection", - "supertip": { - "title": "Toggle worksheet protection", - "description": "Enables or disables worksheet protection." - }, - "actionId": "ToggleProtection" - } - ] - ``` - - > [!TIP] - > The **"controls.actionId"** value must match the **"runtimes.actions.id"** value. +1. Find `TODO2` and replace it with **"toggleProtection"**. This value must match the **"runtimes.actions.id"** value. 1. Save the file. From 484089abd42529b5beac5eb4be1849795d0c97a6 Mon Sep 17 00:00:00 2001 From: Alison McKay Date: Fri, 25 Oct 2024 16:31:51 -0700 Subject: [PATCH 8/8] Add a TODO, add contexts string --- docs/tutorials/excel-tutorial.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/tutorials/excel-tutorial.md b/docs/tutorials/excel-tutorial.md index cfa7301665..6acebef89a 100644 --- a/docs/tutorials/excel-tutorial.md +++ b/docs/tutorials/excel-tutorial.md @@ -517,7 +517,18 @@ The steps vary depending on the type of manifest. > [!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 **"minValue"** of **"1.1"**. +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 @@ -527,7 +538,7 @@ The steps vary depending on the type of manifest. "ribbons": [ { "contexts": [ - // child objects omitted + "default" ], "tabs": [ { @@ -540,7 +551,7 @@ The steps vary depending on the type of manifest. { "id": "toggleProtectionButton", "type": "button", - "label": "Toggle worksheet protection", + "label": , "icons": [ { "size": 16, @@ -559,7 +570,7 @@ The steps vary depending on the type of manifest. "title": "Toggle worksheet protection", "description": "Enables or disables worksheet protection." }, - "actionId": + "actionId": } ] } @@ -570,11 +581,11 @@ The steps vary depending on the type of manifest. ] ``` -1. ** ADD STEPS FOR CONTEXTS ** - 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 **"toggleProtection"**. This value must match the **"runtimes.actions.id"** value. +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.