Skip to content

Commit d7cb48c

Browse files
[Excel] (Tutorial) Add unified manifest steps to Protect a worksheet section (#4873)
* [Excel] (Tutorial) Begin unified manifest updates * Add JSON runtime section * Add JSON section for ribbon button * Make formatting more consistent * Formatting adjustments and slight restructuring * Formatting fixes, typo fix * Reformat to simplify steps * Add a TODO, add contexts string --------- Co-authored-by: Rick Kirkham <[email protected]>
1 parent 245808c commit d7cb48c

File tree

1 file changed

+109
-4
lines changed

1 file changed

+109
-4
lines changed

docs/tutorials/excel-tutorial.md

Lines changed: 109 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,11 @@ In this tutorial, you'll create an Excel task pane add-in that:
4040

4141
![The Yeoman Office Add-in generator command line interface.](../images/yo-office-excel.png)
4242

43+
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.
44+
45+
> [!NOTE]
46+
> 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).
47+
4348
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.
4449

4550
## Create a table
@@ -475,16 +480,114 @@ In this step of the tutorial, you'll add a button to the ribbon that toggles wor
475480

476481
### Configure the manifest to add a second ribbon button
477482

478-
There are two manifest options for Office Add-ins: the unified manifest for Microsoft 365, and the add-in only manifest.
483+
The steps vary depending on the type of manifest.
479484

480-
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
485+
# [Unified manifest for Microsoft 365 (preview)](#tab/jsonmanifest)
481486

482487
> [!NOTE]
483-
> 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.
488+
> 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).
489+
490+
#### Configure the runtime for the ribbon button
484491

485492
1. Open the manifest file **./manifest.json**.
486493

487-
1. (More steps TBD)
494+
1. Find the **"extensions.runtimes"** array and add the following commands runtime object.
495+
496+
```json
497+
"runtimes": [
498+
{
499+
"id": "CommandsRuntime",
500+
"type": "general",
501+
"code": {
502+
"page": "https://localhost:3000/commands.html"
503+
},
504+
"lifetime": "short",
505+
"actions": [
506+
{
507+
"id": <!--TODO1: Set the action ID -->,
508+
"type": "executeFunction",
509+
}
510+
]
511+
}
512+
]
513+
```
514+
515+
1. Find `TODO1` and replace it with **"toggleProtection"**. This matches the `id` for the JavaScript function you create in a later step.
516+
517+
> [!TIP]
518+
> The value of **"actions.id"** must match the first parameter of the call to `Office.actions.associate` in your **commands.js** file.
519+
520+
1. Ensure that the **"requirements.capabilities"** array contains an object that specifies the **"AddinCommands"** requirement set with a **"minVersion"** of **"1.1"**.
521+
522+
```json
523+
"requirements": {
524+
"capabilities": [
525+
{
526+
"name": "AddinCommands",
527+
"minVersion": "1.1"
528+
}
529+
]
530+
},
531+
```
532+
533+
#### Configure the UI for the ribbon button
534+
535+
1. After the **"extensions.runtimes"** array, add the following **"ribbons"** array.
536+
537+
```json
538+
"ribbons": [
539+
{
540+
"contexts": [
541+
"default"
542+
],
543+
"tabs": [
544+
{
545+
"builtInTabID": <!--TODO1: Set the tab ID -->,
546+
"groups": [
547+
{
548+
"id": "worksheetProtectionGroup",
549+
"label": "Contoso Add-in",
550+
"controls": [
551+
{
552+
"id": "toggleProtectionButton",
553+
"type": "button",
554+
"label": <!--TODO2: Label the button -->,
555+
"icons": [
556+
{
557+
"size": 16,
558+
"url": "https://localhost:3000/assets/icon-16.png"
559+
},
560+
{
561+
"size": 32,
562+
"url": "https://localhost:3000/assets/icon-32.png"
563+
},
564+
{
565+
"size": 80,
566+
"url": "https://localhost:3000/assets/icon-80.png"
567+
}
568+
],
569+
"supertip": {
570+
"title": "Toggle worksheet protection",
571+
"description": "Enables or disables worksheet protection."
572+
},
573+
"actionId": <!--TODO3: Set the action ID -->
574+
}
575+
]
576+
}
577+
]
578+
}
579+
]
580+
}
581+
]
582+
```
583+
584+
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).
585+
586+
1. Find `TODO2` and replace it with **"Toggle worksheet protection"**. This is the label for your button in the Excel ribbon.
587+
588+
1. Find `TODO3` and replace it with **"toggleProtection"**. This value must match the **"runtimes.actions.id"** value.
589+
590+
1. Save the file.
488591

489592
# [Add-in only manifest](#tab/xmlmanifest)
490593

@@ -582,6 +685,8 @@ There are two manifest options for Office Add-ins: the unified manifest for Micr
582685

583686
1. Save the file.
584687

688+
---
689+
585690
### Create the function that protects the sheet
586691

587692
1. Open the file **.\commands\commands.js**.

0 commit comments

Comments
 (0)