You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[All Hosts] (manifest) account for unified manifest in UX/UI articles (#4757)
* [All Hosts] (manifest) account for unified manifest in UX/UI articles
* fix link to include
* add auto open articles
* fix date
* link fix
* Apply suggestions from code review
Co-authored-by: Sam Ramon <[email protected]>
* review changes
* Update dialog-api-in-office-add-ins.md
* Update contextual-tabs.md
* metadata date
---------
Co-authored-by: Sam Ramon <[email protected]>
Copy file name to clipboardExpand all lines: docs/design/built-in-button-integration.md
+86-2Lines changed: 86 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: Integrate built-in Office buttons into custom control groups and tabs
3
3
description: Learn how to include built-in Office buttons in your custom command groups and tabs on the Office ribbon.
4
-
ms.date: 06/26/2024
4
+
ms.date: 02/12/2025
5
5
ms.topic: how-to
6
6
ms.localizationpriority: medium
7
7
---
@@ -17,6 +17,88 @@ You can insert built-in Office buttons into your custom control groups on the Of
17
17
> [!IMPORTANT]
18
18
> The add-in feature described in this article is only available in **PowerPoint** on the web, on Windows, and on Mac.
19
19
20
+
Open the tab for the type of manifest your add-in uses for the details of the manifest markup.
21
+
22
+
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
23
+
24
+
[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)]
25
+
26
+
## Insert a built-in control group into a custom tab
27
+
28
+
To insert a built-in Office control group into a custom tab, add a group object with a "builtInGroupId" property *instead of an "id" property* to the "groups" array of your custom tab object. Set to the ID of the built-in group. See [Find the IDs of controls and control groups](#find-the-ids-of-controls-and-control-groups). *The built-in group object should have no other properties.*
29
+
30
+
The following example adds the Office Paragraph control group to a custom tab.
31
+
32
+
33
+
```json
34
+
"extensions": [
35
+
...
36
+
{
37
+
...
38
+
"ribbons": [
39
+
...
40
+
{
41
+
...
42
+
"tabs": [
43
+
{
44
+
"id": "MyTab",
45
+
...
46
+
"groups": [
47
+
... // Optionally, other groups in the tab
48
+
{
49
+
"builtInGroupId": "Paragraph"
50
+
},
51
+
... // Optionally, other groups in the tab
52
+
]
53
+
}
54
+
]
55
+
}
56
+
]
57
+
}
58
+
]
59
+
```
60
+
61
+
## Insert a built-in control into a custom group
62
+
63
+
To insert a built-in Office control into a custom group, add a control object with a "builtInControlId" property *instead of an "id" property* to the "controls" array of your custom group object. Set to the ID of the built-in control. See [Find the IDs of controls and control groups](#find-the-ids-of-controls-and-control-groups). *The built-in control object should have no other properties.*
64
+
65
+
The following example adds the Office Superscript control to a custom group.
66
+
67
+
```json
68
+
"extensions": [
69
+
...
70
+
{
71
+
...
72
+
"ribbons": [
73
+
...
74
+
{
75
+
...
76
+
"tabs": [
77
+
{
78
+
...
79
+
"groups": [
80
+
{
81
+
"id": "MyGroup",
82
+
...
83
+
"controls": [
84
+
... // Optionally, other controls in the group
85
+
{
86
+
"builtInControlId": "Superscript"
87
+
},
88
+
... // Optionally, other controls in the group
89
+
]
90
+
}
91
+
]
92
+
}
93
+
]
94
+
}
95
+
]
96
+
}
97
+
]
98
+
```
99
+
100
+
# [Add-in only manifest](#tab/xmlmanifest)
101
+
20
102
## Insert a built-in control group into a custom tab
21
103
22
104
To insert a built-in Office control group into a tab, add an [OfficeGroup](/javascript/api/manifest/customtab#officegroup) element as a child element in the parent **\<CustomTab\>** element. The `id` attribute of the of the **\<OfficeGroup\>** element is set to the ID of the built-in group. See [Find the IDs of controls and control groups](#find-the-ids-of-controls-and-control-groups).
@@ -62,6 +144,8 @@ The following markup example adds the Office Superscript control to a custom gro
62
144
</ExtensionPoint>
63
145
```
64
146
147
+
---
148
+
65
149
> [!NOTE]
66
150
> Users can customize the ribbon in the Office application. Any user customizations will override your manifest settings. For example, a user can remove a button from any group and remove any group from a tab.
67
151
@@ -71,4 +155,4 @@ The IDs for supported controls and control groups are in files in the repo [Offi
71
155
72
156
## Behavior on unsupported platforms
73
157
74
-
If your add-in is installed on a platform that doesn't support [requirement set AddinCommands 1.3](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets), then the markup described in this article is ignored and the built-in Office controls/groups won't appear in your custom groups/tabs. To prevent your add-in from being installed on platforms that don't support the markup, add a reference to the requirement set in the **\<Requirements\>** section of the manifest. For instructions, see [Specify which Office versions and platforms can host your add-in](../develop/specify-office-hosts-and-api-requirements.md#specify-which-office-versions-and-platforms-can-host-your-add-in). Alternatively, design your add-in to have an experience when **AddinCommands 1.3** isn't supported, as described in [Design for alternate experiences](../develop/specify-office-hosts-and-api-requirements.md#design-for-alternate-experiences). For example, if your add-in contains instructions that assume the built-in buttons are in your custom groups, you could design a version that assumes that the built-in buttons are only in their usual places.
158
+
If your add-in is installed on a platform that doesn't support [requirement set AddinCommands 1.3](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets), then the markup described in this article is ignored and the built-in Office controls/groups won't appear in your custom groups/tabs. To prevent your add-in from being installed on platforms that don't support the markup, you must specify **AddinCommands 1.3** in the manifest as a requirement for installation. For instructions, see [Specify which Office versions and platforms can host your add-in](../develop/specify-office-hosts-and-api-requirements.md#specify-which-office-versions-and-platforms-can-host-your-add-in). Alternatively, design your add-in to have an experience when **AddinCommands 1.3** isn't supported, as described in [Design for alternate experiences](../develop/specify-office-hosts-and-api-requirements.md#design-for-alternate-experiences). For example, if your add-in contains instructions that assume the built-in buttons are in your custom groups, you could design a version that assumes that the built-in buttons are only in their usual places.
Copy file name to clipboardExpand all lines: docs/design/contextual-tabs.md
+57-8Lines changed: 57 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -81,10 +81,7 @@ The following is an example.
81
81
82
82
## Define the groups and controls that appear on the tab
83
83
84
-
Unlike custom core tabs, which are defined with XML in the manifest, custom contextual tabs are defined at runtime with a JSON blob. Your code parses the blob into a JavaScript object, and then passes the object to the [Office.ribbon.requestCreateControls](/javascript/api/office/office.ribbon?view=common-js&preserve-view=true#office-office-ribbon-requestcreatecontrols-member(1)) method. Custom contextual tabs are only present in documents on which your add-in is currently running. This is different from custom core tabs which are added to the Office application ribbon when the add-in is installed and remain present when another document is opened. Also, the `requestCreateControls` method may be run only once in a session of your add-in. If it's called again, an error is thrown.
85
-
86
-
> [!NOTE]
87
-
> The structure of the JSON blob's properties and subproperties (and the key names) is roughly parallel to the structure of the [CustomTab](/javascript/api/manifest/customtab) element and its descendant elements in the manifest XML.
84
+
Unlike custom core tabs, which are defined in the manifest, custom contextual tabs are defined at runtime with a JSON blob. Your code parses the blob into a JavaScript object, and then passes the object to the [Office.ribbon.requestCreateControls](/javascript/api/office/office.ribbon?view=common-js&preserve-view=true#office-office-ribbon-requestcreatecontrols-member(1)) method. Custom contextual tabs are only present in documents on which your add-in is currently running. This is different from custom core tabs which are added to the Office application ribbon when the add-in is installed and remain present when another document is opened. Also, the `requestCreateControls` method may be run only once in a session of your add-in. If it's called again, an error is thrown.
88
85
89
86
We'll construct an example of a contextual tabs JSON blob step-by-step. The full schema for the contextual tab JSON is at [dynamic-ribbon.schema.json](https://developer.microsoft.com/json-schemas/office-js/dynamic-ribbon.schema.json). If you're working in Visual Studio Code, you can use this file to get IntelliSense and to validate your JSON. For more information, see [Editing JSON with Visual Studio Code - JSON schemas and settings](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings).
90
87
@@ -418,7 +415,7 @@ function myContextChanges() {
418
415
419
416
## Open a task pane from contextual tabs
420
417
421
-
To open your task pane from a button on a custom contextual tab, create an action in the JSON with a `type` of `ShowTaskpane`. Then define a button with the `actionId` property set to the `id` of the action. This opens the default task pane specified by the **\<Runtime\>** element in your manifest.
418
+
To open your task pane from a button on a custom contextual tab, create an action in the JSON with a `type` of `ShowTaskpane`. Then define a button with the `actionId` property set to the `id` of the action. This opens the default task pane specified in your manifest.
422
419
423
420
```json
424
421
`{
@@ -568,9 +565,59 @@ Some combinations of platform, Office application, and Office build don't suppor
568
565
569
566
#### Use noncontextual tabs or controls
570
567
571
-
There's a manifest element, [OverriddenByRibbonApi](/javascript/api/manifest/overriddenbyribbonapi), that's designed to create a fallback experience in an add-in that implements custom contextual tabs when the add-in is running on an application or platform that doesn't support custom contextual tabs.
568
+
The add-in's manifest provides a way to create a fallback experience in an add-in that implements custom contextual tabs when the add-in is running on an application or platform that doesn't support custom contextual tabs. The strategy is to define a custom core tab (that is, *noncontextual* custom tab) in the manifest that duplicates the ribbon customizations of the custom contextual tabs in your add-in. Then you use special manifest markup to enable the custom core tab to be visible all the time on platform and version combinations that don't support custom contextual tabs. The process depends on which type of manifest your add-in uses.
569
+
570
+
# [Unified manifest for Microsoft 365](#tab/jsonmanifest)
571
+
572
+
[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)]
573
+
574
+
Begin by defining a custom core tab (that is, *noncontextual* custom tab) in the manifest that duplicates the ribbon customizations of the custom contextual tabs in your add-in. Then, add an "overriddenByRibbonApi" property to each of the control objects and menu items and set its value to "true". The effect of doing so is the following:
575
+
576
+
- If the add-in runs on an application and platform that support custom contextual tabs, then the custom controls and menu items won't appear on the ribbon. Instead, the custom contextual tab will be created when the add-in calls the `requestCreateControls` method.
577
+
- If the add-in runs on an application or platform that *doesn't* support `requestCreateControls`, then the controls and menu items do appear on the custom core tab.
578
+
579
+
The following is an example. Note that "Contoso.MyButton1" will appear on the custom core tab only when custom contextual tabs aren't supported. However, the parent group and custom core tab will appear regardless of whether custom contextual tabs are supported.
580
+
581
+
```json
582
+
"extensions": [
583
+
...
584
+
{
585
+
...
586
+
"ribbons": [
587
+
...
588
+
{
589
+
...
590
+
"tabs": [
591
+
{
592
+
"id": "MyTab",
593
+
"groups": [
594
+
{
595
+
...
596
+
"controls": [
597
+
{
598
+
"id": "Contoso.MyButton1",
599
+
...
600
+
"overriddenByRibbonApi": true
601
+
}
602
+
]
603
+
}
604
+
]
605
+
}
606
+
]
607
+
}
608
+
]
609
+
}
610
+
]
611
+
```
612
+
613
+
When a parent menu control is marked with `"overriddenByRibbonApi": true`, then it isn't visible, and all of its child markup is ignored when custom contextual tabs aren't supported. So, it doesn't matter if any of those child menu items have the "overriddenByRibbonApi" property or what its value is. The implication of this is that if a menu item must be visible in all contexts, then not only should it not be marked with `"overriddenByRibbonApi": true`, but *its ancestor menu control must also not be marked this way*.
614
+
615
+
> [!IMPORTANT]
616
+
> Don't mark *all* of the child items of a menu with `"overriddenByRibbonApi": true`. This is pointless if the parent element is marked with `"overriddenByRibbonApi": true` for reasons given in the preceding paragraph. Moreover, if you leave out the "overriddenByRibbonApi" property on the parent menu control (or set it to `false`), then the parent will appear regardless of whether custom contextual tabs are supported, but it will be empty when they are supported. So, if all the child elements shouldn't appear when custom contextual tabs are supported, mark the *parent* menu control with `"overriddenByRibbonApi": true`.
572
617
573
-
The simplest strategy for using this element is to define a custom core tab (that is, *noncontextual* custom tab) in the manifest that duplicates the ribbon customizations of the custom contextual tabs in your add-in. But you add `<OverriddenByRibbonApi>true</OverriddenByRibbonApi>` as the first child element of the duplicate [Group](/javascript/api/manifest/group), [Control](/javascript/api/manifest/control), and menu **\<Item\>** elements on the custom core tabs. The effect of doing so is the following:
618
+
# [Add-in only manifest](#tab/xmlmanifest)
619
+
620
+
Begin by defining a custom core tab (that is, *noncontextual* custom tab) in the manifest that duplicates the ribbon customizations of the custom contextual tabs in your add-in. But add an [OverriddenByRibbonApi](/javascript/api/manifest/overriddenbyribbonapi) element as the first child element of the duplicate [Group](/javascript/api/manifest/group), [Control](/javascript/api/manifest/control), and menu **\<Item\>** elements on the custom core tabs. The effect of doing so is the following:
574
621
575
622
- If the add-in runs on an application and platform that support custom contextual tabs, then the custom core groups and controls won't appear on the ribbon. Instead, the custom contextual tab will be created when the add-in calls the `requestCreateControls` method.
576
623
- If the add-in runs on an application or platform that *doesn't* support `requestCreateControls`, then the elements do appear on the custom core tab.
@@ -606,9 +653,11 @@ When a parent group, or menu is marked with `<OverriddenByRibbonApi>true</Overri
606
653
> [!IMPORTANT]
607
654
> Don't mark *all* of the child elements of a group or menu with `<OverriddenByRibbonApi>true</OverriddenByRibbonApi>`. This is pointless if the parent element is marked with `<OverriddenByRibbonApi>true</OverriddenByRibbonApi>` for reasons given in the preceding paragraph. Moreover, if you leave out the **\<OverriddenByRibbonApi\>** on the parent (or set it to `false`), then the parent will appear regardless of whether custom contextual tabs are supported, but it will be empty when they are supported. So, if all the child elements shouldn't appear when custom contextual tabs are supported, mark the parent with `<OverriddenByRibbonApi>true</OverriddenByRibbonApi>`.
608
655
656
+
---
657
+
609
658
#### Use APIs that show or hide a task pane in specified contexts
610
659
611
-
As an alternative to **\<OverriddenByRibbonApi\>**, your add-in can define a task pane with UI controls that duplicate the functionality of the controls on a custom contextual tab. Then use the [Office.addin.showAsTaskpane](/javascript/api/office/office.addin?view=common-js&preserve-view=true#office-office-addin-showastaskpane-member(1)) and [Office.addin.hide](/javascript/api/office/office.addin?view=common-js&preserve-view=true#office-office-addin-hide-member(1)) methods to show the task pane when the contextual tab would have been shown if it was supported. For details on how to use these methods, see [Show or hide the task pane of your Office Add-in](../develop/show-hide-add-in.md).
660
+
As an alternative to using the manifest, your add-in can define a task pane with UI controls that duplicate the functionality of the controls on a custom contextual tab. Then use the [Office.addin.showAsTaskpane](/javascript/api/office/office.addin?view=common-js&preserve-view=true#office-office-addin-showastaskpane-member(1)) and [Office.addin.hide](/javascript/api/office/office.addin?view=common-js&preserve-view=true#office-office-addin-hide-member(1)) methods to show the task pane when the contextual tab would have been shown if it was supported. For details on how to use these methods, see [Show or hide the task pane of your Office Add-in](../develop/show-hide-add-in.md).
0 commit comments