From 20047e962f8b8c575cee830d9977f11171e76b74 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Tue, 27 Aug 2024 16:02:23 -0700 Subject: [PATCH 1/9] [All Hosts] (manifest) account for unified manifest in UX/UI articles --- docs/design/add-in-icons-fresh.md | 8 +- docs/design/add-in-icons-monoline.md | 8 +- docs/design/built-in-button-integration.md | 88 +++++++++++++- docs/design/contextual-tabs.md | 64 ++++++++-- docs/design/custom-tab-placement.md | 55 +++++++-- docs/design/disable-add-in-commands.md | 109 ++++++++++++------ .../create-addin-commands-unified-manifest.md | 24 ++-- docs/develop/dialog-api-in-office-add-ins.md | 10 +- docs/develop/show-hide-add-in.md | 11 +- docs/quickstarts/fluent-react-quickstart.md | 7 +- 10 files changed, 305 insertions(+), 79 deletions(-) diff --git a/docs/design/add-in-icons-fresh.md b/docs/design/add-in-icons-fresh.md index 91ca3314b9..3b7db6adce 100644 --- a/docs/design/add-in-icons-fresh.md +++ b/docs/design/add-in-icons-fresh.md @@ -1,7 +1,7 @@ --- title: Fresh style icon guidelines for Office Add-ins description: Guidelines for using Fresh style icons in Office Add-ins. -ms.date: 08/18/2023 +ms.date: 09/19/2024 ms.topic: best-practice ms.localizationpriority: medium --- @@ -128,6 +128,12 @@ Office icons are designed to render well in high contrast modes. Foreground elem ## See also +### Unified manifest reference + +- ["extensions.ribbons" array](/microsoftteams/platform/resources/schema/manifest-schema#extensionsribbons) + +### Add-in only manifest reference + - [Icon manifest element](/javascript/api/manifest/icon) - [IconUrl manifest element](/javascript/api/manifest/iconurl) - [HighResolutionIconUrl manifest element](/javascript/api/manifest/highresolutioniconurl) diff --git a/docs/design/add-in-icons-monoline.md b/docs/design/add-in-icons-monoline.md index 0133b5788a..047907d40b 100644 --- a/docs/design/add-in-icons-monoline.md +++ b/docs/design/add-in-icons-monoline.md @@ -1,7 +1,7 @@ --- title: Monoline style icon guidelines for Office Add-ins description: Guidelines for using Monoline style icons in Office Add-ins. -ms.date: 08/18/2023 +ms.date: 09/19/2024 ms.topic: best-practice ms.localizationpriority: medium --- @@ -205,6 +205,12 @@ The final icons should be saved as .png image files. Use PNG format with a trans ## See also +### Unified manifest reference + +- ["extensions.ribbons" array](/microsoftteams/platform/resources/schema/manifest-schema#extensionsribbons) + +### Add-in only manifest reference + - [Icon manifest element](/javascript/api/manifest/icon) - [IconUrl manifest element](/javascript/api/manifest/iconurl) - [HighResolutionIconUrl manifest element](/javascript/api/manifest/highresolutioniconurl) diff --git a/docs/design/built-in-button-integration.md b/docs/design/built-in-button-integration.md index a1f6f658fd..adc5fc40fb 100644 --- a/docs/design/built-in-button-integration.md +++ b/docs/design/built-in-button-integration.md @@ -1,7 +1,7 @@ --- title: Integrate built-in Office buttons into custom control groups and tabs description: Learn how to include built-in Office buttons in your custom command groups and tabs on the Office ribbon. -ms.date: 06/26/2024 +ms.date: 09/19/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -17,6 +17,88 @@ You can insert built-in Office buttons into your custom control groups on the Of > [!IMPORTANT] > The add-in feature described in this article is only available in **PowerPoint** on the web, on Windows, and on Mac. +Open the tab for the type of manifest your add-in uses for the details of the manifest markup. + +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + +## Insert a built-in control group into a custom tab + +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.* + +The following example adds the Office Paragraph control group to a custom tab. + + +```json +"extensions": [ + ... + { + ... + "ribbons": [ + ... + { + ... + "tabs": [ + { + "id": "MyTab", + ... + "groups": [ + ... // Optionally, other groups in the tab + { + "builtInGroupId": "Paragraph" + }, + ... // Optionally, other groups in the tab + ] + } + ] + } + ] + } +] +``` + +## Insert a built-in control into a custom group + +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.* + +The following example adds the Office Superscript control to a custom group. + +```json +"extensions": [ + ... + { + ... + "ribbons": [ + ... + { + ... + "tabs": [ + { + ... + "groups": [ + { + "id": "MyGroup", + ... + "controls": [ + ... // Optionally, other controls in the group + { + "builtInControlId": "Superscript" + }, + ... // Optionally, other controls in the group + ] + } + ] + } + ] + } + ] + } +] +``` + +# [Add-in only manifest](#tab/xmlmanifest) + ## Insert a built-in control group into a custom tab 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 **\** element. The `id` attribute of the of the **\** 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 ``` +--- + > [!NOTE] > 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. @@ -71,4 +155,4 @@ The IDs for supported controls and control groups are in files in the repo [Offi ## Behavior on unsupported platforms -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 **\** 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. +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. diff --git a/docs/design/contextual-tabs.md b/docs/design/contextual-tabs.md index ba89d20276..e0ce23029b 100644 --- a/docs/design/contextual-tabs.md +++ b/docs/design/contextual-tabs.md @@ -1,7 +1,7 @@ --- title: Create custom contextual tabs in Office Add-ins description: Learn how to add custom contextual tabs to your Office Add-in. -ms.date: 08/21/2024 +ms.date: 09/19/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -60,9 +60,6 @@ Adding custom contextual tabs requires your add-in to use the [shared runtime](. 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. -> [!NOTE] -> 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. - 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). 1. Begin by creating a JSON string with two array properties named `actions` and `tabs`. The `actions` array is a specification of all the functions that can be executed by controls on the contextual tab. The `tabs` array defines one or more contextual tabs, *up to a maximum of 20*. @@ -379,7 +376,7 @@ function myContextChanges() { ## Open a task pane from contextual tabs -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 **\** element in your manifest. +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. ```json `{ @@ -529,9 +526,58 @@ Some combinations of platform, Office application, and Office build don't suppor #### Use noncontextual tabs or controls -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. +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. + +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + +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 a "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: + +- 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. +- 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. + +The following is an example. Note that "MyButton" will appear on the custom core tab only when custom contextual tabs aren't supported. But the parent group and custom core tab will appear regardless of whether custom contextual tabs are supported. + +```json +"extensions": [ + ... + { + ... + "ribbons": [ + ... + { + ... + "tabs": [ + { + "id": "MyTab", + "groups": [ + { + ... + "controls": [ + { + ... + "overriddenByRibbonApi": true + } + ] + } + ] + } + ] + } + ] + } +] +``` + +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*. + +> [!IMPORTANT] +> 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`. -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 `true` as the first child element of the duplicate [Group](/javascript/api/manifest/group), [Control](/javascript/api/manifest/control), and menu **\** elements on the custom core tabs. The effect of doing so is the following: +# [Add-in only manifest](#tab/xmlmanifest) + +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 **\** elements on the custom core tabs. The effect of doing so is the following: - 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. - 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. @@ -567,9 +613,11 @@ When a parent group, or menu is marked with `true [!IMPORTANT] > Don't mark *all* of the child elements of a group or menu with `true`. This is pointless if the parent element is marked with `true` for reasons given in the preceding paragraph. Moreover, if you leave out the **\** 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 `true`. +--- + #### Use APIs that show or hide a task pane in specified contexts -As an alternative to **\**, 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). +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). ### Handle the HostRestartNeeded error diff --git a/docs/design/custom-tab-placement.md b/docs/design/custom-tab-placement.md index f89df6f357..6a0e2ffdb8 100644 --- a/docs/design/custom-tab-placement.md +++ b/docs/design/custom-tab-placement.md @@ -1,7 +1,7 @@ --- title: Position a custom tab on the ribbon description: Learn how to control where a custom tab appears on the Office ribbon and whether it has focus by default. -ms.date: 08/18/2023 +ms.date: 09/19/2024 ms-topic: how-to ms.localizationpriority: medium --- @@ -19,9 +19,46 @@ You can specify where you want your add-in's custom tab to appear on the Office > - The add-in feature and markup described in this article is *only available in PowerPoint on the web*. > - The markup described in this article only works on platforms that support requirement set **AddinCommands 1.3**. See [Behavior on unsupported platforms](#behavior-on-unsupported-platforms) below. -Specify where you want a custom tab to appear by identifying which built-in Office tab you want it to be next to and specifying whether it should be on the left or right side of the built-in tab. Make these specifications by including either an [InsertBefore](/javascript/api/manifest/customtab#insertbefore) (left) or an [InsertAfter](/javascript/api/manifest/customtab#insertafter) (right) element in the [CustomTab](/javascript/api/manifest/customtab) element of your add-in's manifest. (You cannot have both elements.) +By default, a custom tab is added to the end of the ribbon, but you can specify where you want a custom tab to appear by identifying which built-in Office tab you want it to be next to and specifying whether it should be on the left or right side of the built-in tab. Open the tab for the type of manifest your add-in uses for the details of the manifest markup. -In the following example, the custom tab is configured to appear *just after* the **Review** tab. Note that the value of the **\** element is the ID of the built-in Office tab. +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + +To position your custom tab, include a "position" property in the tab object. Set the "position.builtInTabId" property to the ID of the built in tab that you want your custom tab to be next to. (See [Find the IDs of built-in Office ribbon tabs](../develop/built-in-ui-ids.md).) Set the "position.align" property to either "before" (left) or "after" (right). + +In the following example, the custom tab is configured to appear *just after* the **Review** tab. + +```json +"extensions": [ + ... + { + ... + "ribbons": [ + ... + { + ... + "tabs": [ + { + "id": "MyTab", + ... + "position": { + "builtInTabId": "TabReview", + "align": "after" + } + } + ] + } + ] + } +] +``` + +# [Add-in only manifest](#tab/xmlmanifest) + +To position your custom tab, include either an [InsertBefore](/javascript/api/manifest/customtab#insertbefore) (left) or an [InsertAfter](/javascript/api/manifest/customtab#insertafter) (right) element in the [CustomTab](/javascript/api/manifest/customtab) element of your add-in's manifest. (You cannot have both elements.) + +In the following example, the custom tab is configured to appear *just after* the **Review** tab. Note that the value of the **\** element is the ID of the built-in Office tab. See [Find the IDs of built-in Office ribbon tabs](../develop/built-in-ui-ids.md). ```xml @@ -35,21 +72,21 @@ In the following example, the custom tab is configured to appear *just after* th ``` -Keep the following points in mind. +--- + +## How user actions can affect custom tab positioning -- The **\** and **\** elements are optional. If you use neither, then your custom tab will appear as the rightmost tab on the ribbon. -- The **\** and **\** elements are mutually exclusive. You can't use both. - If the user installs more than one add-in whose custom tab is configured for the same place, say after the **Review** tab, then the tab for the most recently installed add-in will be located in that place. The tabs of the previously installed add-ins will be moved over one place. For example, the user installs add-ins A, B, and C in that order and all are configured to insert a tab after the **Review** tab, then the tabs will appear in this order: **Review**, **AddinCTab**, **AddinBTab**, **AddinATab**. - Users can customize the ribbon in the Office application. For example, a user can move or hide your add-in's tab. You cannot prevent this or detect that it has happened. -- If a user moves one of the built-in tabs, then Office interprets the **\** and **\** elements in terms of *the default location of the built-in tab*. For example, if the user moves the **Review** tab to the right end of the ribbon, Office will interpret the markup in the previous example as meaning "put the custom tab just to the right of *where the **Review** tab would be by default*." +- If a user moves one of the built-in tabs, then Office interprets the positioning markup in the manifest in terms of *the default location of the built-in tab*. For example, if the user moves the **Review** tab to the right end of the ribbon, Office will interpret the markup in the previous example as meaning "put the custom tab just to the right of *where the **Review** tab would be by default*." ## Specify which tab has focus when the document opens -Office always gives default focus to the tab that's immediately to the right of the **File** tab. By default this is the **Home** tab. If you configure your custom tab to be before the **Home** tab, with `TabHome`, then your custom tab will have focus when the document opens. +Office always gives default focus to the tab that's immediately to the right of the **File** tab. By default this is the **Home** tab. If you configure your custom tab to be before the **Home** tab, then your custom tab will have focus when the document opens. > [!IMPORTANT] > Giving excessive prominence to your add-in inconveniences and annoys users and administrators. Don't position a custom tab before the **Home** tab unless your add-in is the primary way users will interact with the document. ## Behavior on unsupported platforms -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 your custom tab will appear as the rightmost tab on the ribbon. 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 **\** 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 alternate 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 custom tab is where you want it, you could have an alternate version that assumes the tab is the rightmost. +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 your custom tab will appear as the rightmost tab on the ribbon. 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 alternate 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 custom tab is where you want it, you could have an alternate version that assumes the tab is the rightmost. diff --git a/docs/design/disable-add-in-commands.md b/docs/design/disable-add-in-commands.md index 60008ce1a9..ced0650c9c 100644 --- a/docs/design/disable-add-in-commands.md +++ b/docs/design/disable-add-in-commands.md @@ -1,7 +1,7 @@ --- title: Enable and Disable Add-in Commands description: Learn how to change the enabled or disabled status of custom ribbon buttons and menu items in your Office Web Add-in. -ms.date: 08/05/2024 +ms.date: 09/19/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -21,19 +21,52 @@ The APIs described in this article are available in **Excel**, **PowerPoint**, a ## Shared runtime required -The APIs and manifest markup described in this article require that the add-in's manifest specify that it should use a [shared runtime](../testing/runtimes.md#shared-runtime). To do this, take the following steps. +The APIs and manifest markup described in this article require that the add-in's manifest specify that it should use a [shared runtime](../testing/runtimes.md#shared-runtime). For more information, see [Configure an add-in to use a shared runtime](../develop/configure-your-add-in-to-use-a-shared-runtime.md). -1. In the [Runtimes](/javascript/api/manifest/runtimes) element in the manifest, add the following child element: ``. (If there isn't already a **\** element in the manifest, create it as the first child under the **\** element in the **\** section.) -1. In the [Resources.Urls](/javascript/api/manifest/resources) section of the manifest, add the following child element: ``, where `{MyDomain}` is the domain of the add-in and `{path-to-start-page}` is the path for the start page of the add-in; for example: ``. -1. Depending on whether your add-in contains a task pane, a function file, or an Excel custom function, you must do one or more of the following three steps. +## Set the default state to disabled - - If the add-in contains a task pane, set the `resid` attribute of the [Action](/javascript/api/manifest/action).[SourceLocation](/javascript/api/manifest/sourcelocation) element to exactly the same string as you used for the `resid` of the **\** element in step 1; for example, `Contoso.SharedRuntime.Url`. The element should look like this: ``. - - If the add-in contains an Excel custom function, set the `resid` attribute of the [Page](/javascript/api/manifest/page).[SourceLocation](/javascript/api/manifest/sourcelocation) element exactly the same string as you used for the `resid` of the **\** element in step 1; for example, `Contoso.SharedRuntime.Url`. The element should look like this: ``. - - If the add-in contains a function file, set the `resid` attribute of the [FunctionFile](/javascript/api/manifest/functionfile) element to exactly the same string as you used for the `resid` of the **\** element in step 1; for example, `Contoso.SharedRuntime.Url`. The element should look like this: ``. +By default, any Add-in Command is enabled when the Office application launches. If you want a custom button or menu item to be disabled when the Office application launches, you specify this in the manifest. The process depends on which type of manifest your add-in uses. -## Set the default state to disabled +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] -By default, any Add-in Command is enabled when the Office application launches. If you want a custom button or menu item to be disabled when the Office application launches, you specify this in the manifest. Just add an [Enabled](/javascript/api/manifest/enabled) element (with the value `false`) immediately *below* (not inside) the [Action](/javascript/api/manifest/action) element in the declaration of the control. The following shows the basic structure. +Just add an "enabled" property with the value `false` to the control or menu item object. The following shows the basic structure. + +```json +"extensions": [ + ... + { + ... + "ribbons": [ + ... + { + ... + "tabs": [ + { + "id": "MyTab", + "groups": [ + { + ... + "controls": [ + { + ... + "enabled": false + } + ] + } + ] + } + ] + } + ] + } +] +``` + +# [Add-in only manifest](#tab/xmlmanifest) + +Just add an [Enabled](/javascript/api/manifest/enabled) element (with the value `false`) immediately *below* (not inside) the [Action](/javascript/api/manifest/action) element in the declaration of the control. The following shows the basic structure. ```xml @@ -57,6 +90,8 @@ By default, any Add-in Command is enabled when the Office application launches. ``` +--- + ## Change the state programmatically The essential steps to changing the enabled status of an Add-in Command are: @@ -129,17 +164,17 @@ Third, define the `enableChartFormat` handler. The following is a simple example ```javascript function enableChartFormat() { const button = { - id: "ChartFormatButton", - enabled: true - }; + id: "ChartFormatButton", + enabled: true + }; const parentGroup = { - id: "MyGroup", - controls: [button] - }; + id: "MyGroup", + controls: [button] + }; const parentTab = { - id: "CustomChartTab", - groups: [parentGroup] - }; + id: "CustomChartTab", + groups: [parentGroup] + }; const ribbonUpdater = {tabs: [parentTab]}; Office.ribbon.requestUpdate(ribbonUpdater); } @@ -163,17 +198,17 @@ The following example shows a function that disables a button and records the bu ```javascript function disableChartFormat() { const button = { - id: "ChartFormatButton", - enabled: false - }; + id: "ChartFormatButton", + enabled: false + }; const parentGroup = { - id: "MyGroup", - controls: [button] - }; + id: "MyGroup", + controls: [button] + }; const parentTab = { - id: "CustomChartTab", - groups: [parentGroup] - }; + id: "CustomChartTab", + groups: [parentGroup] + }; const ribbonUpdater = {tabs: [parentTab]}; Office.ribbon.requestUpdate(ribbonUpdater); @@ -205,17 +240,17 @@ In some scenarios, Office is unable to update the ribbon and will return an erro function disableChartFormat() { try { const button = { - id: "ChartFormatButton", - enabled: false - }; + id: "ChartFormatButton", + enabled: false + }; const parentGroup = { - id: "MyGroup", - controls: [button] - }; + id: "MyGroup", + controls: [button] + }; const parentTab = { - id: "CustomChartTab", - groups: [parentGroup] - }; + id: "CustomChartTab", + groups: [parentGroup] + }; const ribbonUpdater = {tabs: [parentTab]}; Office.ribbon.requestUpdate(ribbonUpdater); diff --git a/docs/develop/create-addin-commands-unified-manifest.md b/docs/develop/create-addin-commands-unified-manifest.md index c386417963..147fdba4fd 100644 --- a/docs/develop/create-addin-commands-unified-manifest.md +++ b/docs/develop/create-addin-commands-unified-manifest.md @@ -1,7 +1,7 @@ --- title: Create add-in commands with the unified manifest for Microsoft 365 description: Configure the unified manifest for Microsoft 365 to define add-in commands for Excel, Outlook, PowerPoint, and Word. Use add-in commands to create UI elements, add buttons or lists, and perform actions. -ms.date: 07/18/2024 +ms.date: 09/19/2024 ms.localizationpriority: medium --- @@ -11,6 +11,8 @@ Add-in commands provide an easy way to customize the default Office user interfa This article describes how to configure the [Unified manifest for Microsoft 365](unified-manifest-overview.md) to define add-in commands and how to create the code for [function commands](../design/add-in-commands.md#types-of-add-in-commands). +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + > [!TIP] > Instructions for creating add-in commands with the add-in only manifest are in [Create add-in commands with the add-in only manifest](create-addin-commands.md). @@ -33,16 +35,13 @@ The following subsections explain how to include a [task pane command](../design 1. Open the unified manifest and find the "extensions.runtimes" array. 1. Ensure that there is a runtime object that has an "actions.type" property with the value "openPage". This type of runtime opens a task pane. -1. Ensure that the "requirements.capabilities" array contains an object that specifies a [Requirement Set](office-versions-and-requirement-sets.md) that supports add-in commands. For Outlook the minimum requirement set for add-in commands is [Mailbox 1.3](/javascript/api/requirement-sets/outlook/requirement-set-1.3/outlook-requirement-set-1.3). - - > [!NOTE] - > When support for the unified manifest is extended to other Office host applications, the minimum requirement set for add-in commands in those other hosts will be [AddinCommands 1.1](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets). +1. Ensure that the "requirements.capabilities" array contains an object that specifies a [Requirement Set](office-versions-and-requirement-sets.md) that supports add-in commands. For Outlook the minimum requirement set for add-in commands is [Mailbox 1.3](/javascript/api/requirement-sets/outlook/requirement-set-1.3/outlook-requirement-set-1.3). For other Office host applications, the minimum requirement set for add-in commands is [AddinCommands 1.1](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets). 1. Ensure that the "id" of the runtime object has a descriptive name such as "TaskPaneRuntime". 1. Ensure that the "code.page" property of the runtime object is set to the URL of the page that should open in the task pane, such as `"https://localhost:3000/taskpane.html"`. 1. Ensure that the "actions.view" of the runtime object has a name that describes the content of the page that you set in the preceding step, such as "homepage" or "dashboard". 1. Ensure that the "actions.id" of the runtime object has a descriptive name such as "ShowTaskPane" that indicates what happens when the user selects the add-in command button or menu item. -1. Set the other properties and subproperties of the runtime object as shown in the following completed example of a runtime object. The "type" and "lifetime" properties are required and in Outlook Add-ins (which is the only host that currently supports the unified manifest) they always have the values shown in this example. +1. Set the other properties and subproperties of the runtime object as shown in the following completed example of a runtime object. The "type" and "lifetime" properties are required and in Outlook Add-ins. They always have the values shown in this example. ```json "runtimes": [ @@ -121,7 +120,7 @@ The following subsections explain how to include a [task pane command](../design ``` > [!NOTE] - > The only allowed value for the "builtInTabID" property is "TabDefault", which in Outlook is either the **Home**, **Message**, or **Meeting** tab. When support for the unified manifest is added to other Office host applications, there will be other possible values. + > For a list of the possible values of the "builtInTabID" property, see [Find the IDs of built-in Office ribbon tabs](built-in-ui-ids.md). 1. Ensure that the "groups" array has an object to define the custom control group that will hold your add-in command UI controls. The following is an example. Note the following about this JSON: @@ -261,10 +260,7 @@ The following subsections explain how to include a [function command](../design/ 1. Open the unified manifest and find the "extensions.runtimes" array. 1. Ensure that there is a runtime object that has a "actions.type" property with the value "executeFunction". -1. Ensure that the "requirements.capabilities" array contains objects that specify any [Requirement Sets](office-versions-and-requirement-sets.md) that are needed to support the APIs add-in commands. For Outlook, the minimum requirement set for add-in commands is [Mailbox 1.3](/javascript/api/requirement-sets/outlook/requirement-set-1.3/outlook-requirement-set-1.3). But if your function command calls that API that is part of later **Mailbox** requirement set, such as **Mailbox 1.5**, then you need to specify the later version (e.g., "1.5") as the "minVersion" value. - - > [!NOTE] - > When support for the unified manifest is extended to other Office host applications, the minimum requirement set for add-in commands in those other hosts will be [AddinCommands 1.1](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets). +1. Ensure that the "requirements.capabilities" array contains objects that specify any [Requirement Sets](office-versions-and-requirement-sets.md) that are needed to support the APIs add-in commands. For Outlook, the minimum requirement set for add-in commands is [Mailbox 1.3](/javascript/api/requirement-sets/outlook/requirement-set-1.3/outlook-requirement-set-1.3). But if your function command calls that API that is part of later **Mailbox** requirement set, such as **Mailbox 1.5**, then you need to specify the later version (e.g., "1.5") as the "minVersion" value. For other Office host applications, the minimum requirement set for add-in commands is [AddinCommands 1.1](/javascript/api/requirement-sets/common/add-in-commands-requirement-sets). 1. Ensure that the "id" of the runtime object has a descriptive name such as "CommandsRuntime". 1. Ensure that the "code.page" property of the runtime object is set to the URL of the UI-less HTML page that loads your function file, such as `"https://localhost:3000/commands.html"`. @@ -273,7 +269,7 @@ The following subsections explain how to include a [function command](../design/ > [!IMPORTANT] > The value of "actions.id" must exactly match the first parameter of the call to `Office.actions.associate` in the function file. -1. Set the other properties and subproperties of the runtime object as shown in the following completed example of a runtime object. The "type" and "lifetime" properties are required and they always have the values shown in Outlook add-ins, which is the only host that currently supports the unified manifest. +1. Set the other properties and subproperties of the runtime object as shown in the following completed example of a runtime object. ```json "runtimes": [ @@ -343,7 +339,7 @@ The following subsections explain how to include a [function command](../design/ ``` > [!NOTE] - > The only allowed value for the "builtInTabID" property is "TabDefault", which in Outlook is either the **Home**, **Message**, or **Meeting** tab. When support for the unified manifest is added to other Office host applications, there will be other possible values. + > For a list of the possible values of the "builtInTabID" property, see [Find the IDs of built-in Office ribbon tabs](built-in-ui-ids.md). 1. Ensure that the "groups" array has an object to define the custom control group that will hold your add-in command UI controls. The following is an example. Note the following about this JSON: @@ -476,7 +472,7 @@ Carry out the steps of the following sections: ``` > [!NOTE] - > The only allowed value for the "builtInTabID" property is "TabDefault", which in Outlook is either the **Home**, **Message**, or **Meeting** tab. When support for the unified manifest is added to other Office host applications, there will be other possible values. + > For a list of the possible values of the "builtInTabID" property, see [Find the IDs of built-in Office ribbon tabs](built-in-ui-ids.md). 1. Ensure that the "groups" array has an object to define the custom control group that will hold your drop down menu control. The following is an example. Note the following about this JSON: diff --git a/docs/develop/dialog-api-in-office-add-ins.md b/docs/develop/dialog-api-in-office-add-ins.md index 0ecf31fcac..e3bb83602a 100644 --- a/docs/develop/dialog-api-in-office-add-ins.md +++ b/docs/develop/dialog-api-in-office-add-ins.md @@ -1,7 +1,7 @@ --- title: Use the Office dialog API in your Office Add-ins description: Learn the basics of creating a dialog box in an Office Add-in. -ms.date: 05/16/2024 +ms.date: 09/19/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -330,7 +330,7 @@ Because you can make multiple `messageChild` calls from the host page, but you h > In some situations, the `messageChild` API, which is a part of the [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets), may not be supported. For example, `messageChild` isn't supported in volume-licensed perpetual Outlook 2016 and volume-licensed perpetual Outlook 2019. Some alternative ways for parent-to-dialog-box messaging are described in [Alternative ways of passing messages to a dialog box from its host page](parent-to-dialog.md). > [!IMPORTANT] -> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the **\** section of an add-in manifest. You will have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). Support for manifest requirements is under development. +> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the add-in manifest. You will have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). Support for manifest requirements is under development. ### Cross-domain messaging to the dialog runtime @@ -351,7 +351,11 @@ If the message doesn't include sensitive data, you can set the `targetOrigin` to dialog.messageChild(messageToDialog, { targetOrigin: "*" }); ``` -Because the runtime that is hosting the dialog can't access the **\** section of the manifest and thereby determine whether the domain *from which the message comes* is trusted, you must use the `DialogParentMessageReceived` handler to determine this. The object that is passed to the handler contains the domain that is currently hosted in the parent as its `origin` property. The following is an example of how to use the property. +The add-in's manifest specifies trusted domains. In the unified manifest for Microsoft 365, this is specified in the "validDomains" property. In the add-only manifest, this is specified in the **\** element. + +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + +But the runtime that is hosting the dialog can't access the manifest and thereby determine whether the domain *from which the message comes* is trusted, you must use the `DialogParentMessageReceived` handler to determine this. The object that is passed to the handler contains the domain that is currently hosted in the parent as its `origin` property. The following is an example of how to use the property. ```javascript function onMessageFromParent(arg) { diff --git a/docs/develop/show-hide-add-in.md b/docs/develop/show-hide-add-in.md index b6a6c2cd38..55ea6a0033 100644 --- a/docs/develop/show-hide-add-in.md +++ b/docs/develop/show-hide-add-in.md @@ -1,7 +1,7 @@ --- title: Show or hide the task pane of your Office Add-in description: Learn how to programmatically hide or show the user interface of an add-in while it runs continuously. -ms.date: 08/15/2022 +ms.date: 09/19/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -36,7 +36,14 @@ The previous code is a handler that is registered for the [Office.Worksheet.onDe ## Additional details on showing the task pane -When you call `Office.addin.showAsTaskpane()`, Office will display in a task pane the file that you assigned as the resource ID (`resid`) value of the task pane. This `resid` value can be assigned or changed by opening your **manifest.xml** file and locating **\** inside the `` element. +When you call `Office.addin.showAsTaskpane()`, Office will display in a task pane the file that you specified in the manifest. The configuration depends on what type of manifest you are using. + +- **Unified manifest for Microsoft 365**: The URL of the file is assigned as the value of a "runtimes.code.page" property of the runtime object which has an action object of type "openPage". + + [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + +- **Add-in only manifest**: The URL of the file is assigned as the resource ID (`resid`) value of the task pane. This `resid` value can be assigned or changed by opening your manifest file and locating **\** inside the `` element. + (See [Configure your Office Add-in to use a shared runtime](configure-your-add-in-to-use-a-shared-runtime.md) for additional details.) Since `Office.addin.showAsTaskpane()` is an asynchronous method, your code will continue running until the method is complete. Wait for this completion with either the `await` keyword or a `then()` method, depending on which JavaScript syntax you are using. diff --git a/docs/quickstarts/fluent-react-quickstart.md b/docs/quickstarts/fluent-react-quickstart.md index b68ab850f4..d273c0884d 100644 --- a/docs/quickstarts/fluent-react-quickstart.md +++ b/docs/quickstarts/fluent-react-quickstart.md @@ -1,7 +1,7 @@ --- title: Fluent UI React in Office Add-ins description: Learn how to create an Office Add-in that uses Fluent UI React. -ms.date: 12/13/2023 +ms.date: 09/19/2024 ms.topic: how-to ms.service: microsoft-365 ms.localizationpriority: medium @@ -51,7 +51,10 @@ After you complete the wizard, the generator creates the project and installs su The add-in project that you've created with the Yeoman generator contains sample code for a basic task pane add-in. If you'd like to explore the components of your add-in project, open the project in your code editor and review the following files. The file name extensions depend on which language you choose. TypeScript extensions are in parentheses. When you're ready to try out your add-in, proceed to the next section. -- The **./manifest.xml** file in the root directory of the project defines the settings and capabilities of the add-in. To learn more about the **manifest.xml** file, see [Office Add-ins with the add-in only manifest](../develop/xml-manifest-overview.md). +- The **./manifest.xml** or **./manifest.json** file in the root directory of the project defines the settings and capabilities of the add-in. To learn more about the **manifest.xml** file, see [Office Add-ins with the add-in only manifest](../develop/xml-manifest-overview.md). To learn more about the **manifest.json** file, see [Office Add-ins with the unified app manifest for Microsoft 365](../develop/unified-manifest-overview.md). + + [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + - The **./src/taskpane/taskpane.html** file contains the HTML markup for the task pane and loads the Office JavaScript Library. It also tests whether the webview control supports Fluent UI React v9 and displays a special message if it doesn't. - The **./src/taskpane/index.jsx (tsx)** file is the React root component. It loads React and Fluent UI React, ensures that the Office JavaScript library has been loaded, and applies the Fluent-defined theme. - The **./src/taskpane/office-document.js (ts)** file contains the Office JavaScript API code that facilitates interaction between the task pane and the Office client application. From 148a27cdf6cabe6ad27227a716e126956ac95a91 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Tue, 27 Aug 2024 16:08:56 -0700 Subject: [PATCH 2/9] fix link to include --- docs/includes/unified-manifest-support-note.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/includes/unified-manifest-support-note.md diff --git a/docs/includes/unified-manifest-support-note.md b/docs/includes/unified-manifest-support-note.md new file mode 100644 index 0000000000..2810e966df --- /dev/null +++ b/docs/includes/unified-manifest-support-note.md @@ -0,0 +1,2 @@ +> [!NOTE] +> The [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) can be used in production Outlook add-ins. It is available only as a preview for Excel, PowerPoint, and Word add-ins. \ No newline at end of file From df01ca8a7cad47ee433b2d7b85ba2a505054da70 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Wed, 28 Aug 2024 11:18:10 -0700 Subject: [PATCH 3/9] add auto open articles --- ...ically-open-a-task-pane-with-a-document.md | 35 ++++++++++++++++++- .../automatically-open-on-installation.md | 34 +++++++++++++++++- 2 files changed, 67 insertions(+), 2 deletions(-) diff --git a/docs/develop/automatically-open-a-task-pane-with-a-document.md b/docs/develop/automatically-open-a-task-pane-with-a-document.md index 9424e8ee10..3e0da3ef7f 100644 --- a/docs/develop/automatically-open-a-task-pane-with-a-document.md +++ b/docs/develop/automatically-open-a-task-pane-with-a-document.md @@ -2,7 +2,7 @@ title: Automatically open a task pane with a document description: Learn how to configure an Office Add-in to open automatically when a document opens. ms.topic: how-to -ms.date: 05/05/2023 +ms.date: 09/19/2024 ms.localizationpriority: medium --- @@ -56,6 +56,37 @@ Apply the following best practices when you use the autoopen feature. ### Step 1: Specify the task pane to open +Configure the manifest to specify the task pane page that should open automatically. The process depends on what type of manifest the add-in uses. + + +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + +To specify the task pane to open automatically, find the runtime object in the "runtimes" array whose "code.page" property is set to the URL of the page that you want to open automatically. Ensure that the "actions" array in this same runtime object has at least one action whose "type" value is "openPage". Add a "view" property to this action object and set it to "Office.AutoShowTaskpaneWithDocument". You can only set this value on one action object and it must an action of type "openPage". If you set this value on multiple actions, the first occurrence of the value will be recognized and the others will be ignored. + +The following example shows a "view" value set to "Office.AutoShowTaskpaneWithDocument". + +```json +"runtimes": [ + { + ... + "code": { + "page": "https://contoso.com/taskpane.html" + }, + "actions": [ + { + "id": "ShowTaskPane", + "type": "openPage", + "view": "Office.AutoShowTaskpaneWithDocument" + } + ] + } +] +``` + +# [Add-in only manifest](#tab/xmlmanifest) + To specify the task pane to open automatically, set the [TaskpaneId](/javascript/api/manifest/action#taskpaneid) value to **Office.AutoShowTaskpaneWithDocument**. You can only set this value on one task pane. If you set this value on multiple task panes, the first occurrence of the value will be recognized and the others will be ignored. The following example shows the TaskPaneId value set to Office.AutoShowTaskpaneWithDocument. @@ -67,6 +98,8 @@ The following example shows the TaskPaneId value set to Office.AutoShowTaskpaneW ``` +--- + ### Step 2: Tag the document to automatically open the task pane You can tag the document to trigger the autoopen feature in one of two ways. Pick the alternative that works best for your scenario. diff --git a/docs/develop/automatically-open-on-installation.md b/docs/develop/automatically-open-on-installation.md index 3c013ae9c4..0df790d1b7 100644 --- a/docs/develop/automatically-open-on-installation.md +++ b/docs/develop/automatically-open-on-installation.md @@ -30,7 +30,37 @@ The new behavior is as follows: > [!NOTE] > If for any reason, the add-in command that launches the task pane cannot be manually selected by a user at start up, such as when it's [configured to be disabled](../design/disable-add-in-commands.md) at start up, then it won't be automatically opened regardless of configuration. -## Configure default task pane +## Configure default task pane in the manifest + +The process for specifying the default task pane depends on the type of manifest the add-in uses. + +# [Unified manifest for Microsoft 365](#tab/jsonmanifest) + +[!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] + +To specify the default task pane, find the runtime object in the "runtimes" array whose "code.page" property is set to the URL of the page that you want to be the default. Ensure that the "actions" array in this same runtime object has at least one action whose "type" value is "openPage". Add a "view" property to this action object and set it to "Office.AutoShowTaskpaneWithDocument". You can only set this value on one action object and it must an action of type "openPage". If you set this value on multiple actions, the first occurrence of the value will be recognized as the default and the others will be ignored. + +The following example shows a "view" value set to "Office.AutoShowTaskpaneWithDocument". + +```json +"runtimes": [ + { + ... + "code": { + "page": "https://contoso.com/taskpane.html" + }, + "actions": [ + { + "id": "ShowTaskPane", + "type": "openPage", + "view": "Office.AutoShowTaskpaneWithDocument" + } + ] + } +] +``` + +# [Add-in only manifest](#tab/xmlmanifest) To designate a task pane as the default, add a [TaskpaneId](/javascript/api/manifest/action#taskpaneid) element as the first child of the **\** element and set its value to **Office.AutoShowTaskpaneWithDocument**. The following is an example. @@ -41,6 +71,8 @@ To designate a task pane as the default, add a [TaskpaneId](/javascript/api/mani ``` +--- + > [!TIP] > If you want your add-in to automatically launch whenever the user reopens the document, you need to take further configuration steps. For details and advice about when to use this feature, see [Automatically open a task pane with a document](automatically-open-a-task-pane-with-a-document.md). From 59e59e266ef091650bbff739f00e0d5b45abfe66 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Wed, 28 Aug 2024 11:19:19 -0700 Subject: [PATCH 4/9] fix date --- docs/develop/automatically-open-on-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/automatically-open-on-installation.md b/docs/develop/automatically-open-on-installation.md index 0df790d1b7..86ce26f9d0 100644 --- a/docs/develop/automatically-open-on-installation.md +++ b/docs/develop/automatically-open-on-installation.md @@ -2,7 +2,7 @@ title: Automatically open a task pane when an add-in is installed description: Learn how to configure an Office Add-in to open automatically when it's installed. ms.topic: how-to -ms.date: 02/23/2024 +ms.date: 09/19/2024 ms.localizationpriority: medium --- From b7108a707f5b6dd9080071ad90dfd860774faac6 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Wed, 28 Aug 2024 13:04:07 -0700 Subject: [PATCH 5/9] link fix --- docs/develop/automatically-open-on-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/automatically-open-on-installation.md b/docs/develop/automatically-open-on-installation.md index 86ce26f9d0..d22b31ba74 100644 --- a/docs/develop/automatically-open-on-installation.md +++ b/docs/develop/automatically-open-on-installation.md @@ -24,7 +24,7 @@ By default, task pane add-ins that do *not* include any [add-in commands](../des The new behavior is as follows: - If the add-in has just one [task pane command](../design/add-in-commands.md#types-of-add-in-commands), then the add-in's ribbon tab is selected and the task pane opens automatically upon installation. You don't need to configure anything. -- If the add-in has multiple task pane commands, and one is configured to be the default (see [Configure default task pane](#configure-default-task-pane)), then the add-in's ribbon tab is selected and the default task pane opens automatically upon installation. +- If the add-in has multiple task pane commands, and one is configured to be the default (see [Configure default task pane](#configure-default-task-pane-in-the-manifest)), then the add-in's ribbon tab is selected and the default task pane opens automatically upon installation. - If the add-in has multiple task pane commands, but none is configured to be the default, then the add-in's ribbon tab is selected automatically upon installation and a callout appears near it notifying the user of the new add-in, but no task pane is opened. This is the same as the historic default behavior. > [!NOTE] From 0cede90c5c783ed9a2e0a4e8aa27e5771e8cfe14 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Sat, 7 Sep 2024 12:14:04 -0700 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: Sam Ramon <15154970+samantharamon@users.noreply.github.com> --- docs/design/contextual-tabs.md | 6 +-- docs/design/custom-tab-placement.md | 4 +- docs/design/disable-add-in-commands.md | 54 +++++++++---------- ...ically-open-a-task-pane-with-a-document.md | 2 +- docs/develop/dialog-api-in-office-add-ins.md | 6 +-- docs/develop/show-hide-add-in.md | 2 +- .../includes/unified-manifest-support-note.md | 2 +- 7 files changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/design/contextual-tabs.md b/docs/design/contextual-tabs.md index e0ce23029b..fcb29eb333 100644 --- a/docs/design/contextual-tabs.md +++ b/docs/design/contextual-tabs.md @@ -58,7 +58,7 @@ Adding custom contextual tabs requires your add-in to use the [shared runtime](. ## Define the groups and controls that appear on the tab -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. +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. 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). @@ -532,12 +532,12 @@ The add-in's manifest provides a way to create a fallback experience in an add-i [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] -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 a "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: +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: - 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. - 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. -The following is an example. Note that "MyButton" will appear on the custom core tab only when custom contextual tabs aren't supported. But the parent group and custom core tab will appear regardless of whether custom contextual tabs are supported. +The following is an example. Note that "MyButton" 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. ```json "extensions": [ diff --git a/docs/design/custom-tab-placement.md b/docs/design/custom-tab-placement.md index 6a0e2ffdb8..dddaeef1c6 100644 --- a/docs/design/custom-tab-placement.md +++ b/docs/design/custom-tab-placement.md @@ -19,13 +19,13 @@ You can specify where you want your add-in's custom tab to appear on the Office > - The add-in feature and markup described in this article is *only available in PowerPoint on the web*. > - The markup described in this article only works on platforms that support requirement set **AddinCommands 1.3**. See [Behavior on unsupported platforms](#behavior-on-unsupported-platforms) below. -By default, a custom tab is added to the end of the ribbon, but you can specify where you want a custom tab to appear by identifying which built-in Office tab you want it to be next to and specifying whether it should be on the left or right side of the built-in tab. Open the tab for the type of manifest your add-in uses for the details of the manifest markup. +By default, a custom tab is added to the end of the ribbon. However, you can specify where you want a custom tab to appear by identifying which built-in Office tab you want it to be next to and specifying whether it should be on the left or right side of the built-in tab. Open the tab for the type of manifest your add-in uses for the details of the manifest markup. # [Unified manifest for Microsoft 365](#tab/jsonmanifest) [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] -To position your custom tab, include a "position" property in the tab object. Set the "position.builtInTabId" property to the ID of the built in tab that you want your custom tab to be next to. (See [Find the IDs of built-in Office ribbon tabs](../develop/built-in-ui-ids.md).) Set the "position.align" property to either "before" (left) or "after" (right). +To position your custom tab, include a "position" property in the "extensions.ribbons.tabs" object. Set the "position.builtInTabId" property to the ID of the built-in tab that you want your custom tab to be next to. (See [Find the IDs of built-in Office ribbon tabs](../develop/built-in-ui-ids.md).) Set the "position.align" property to either "before" (left) or "after" (right). In the following example, the custom tab is configured to appear *just after* the **Review** tab. diff --git a/docs/design/disable-add-in-commands.md b/docs/design/disable-add-in-commands.md index ced0650c9c..33963aa83f 100644 --- a/docs/design/disable-add-in-commands.md +++ b/docs/design/disable-add-in-commands.md @@ -164,17 +164,17 @@ Third, define the `enableChartFormat` handler. The following is a simple example ```javascript function enableChartFormat() { const button = { - id: "ChartFormatButton", - enabled: true - }; + id: "ChartFormatButton", + enabled: true + }; const parentGroup = { - id: "MyGroup", - controls: [button] - }; + id: "MyGroup", + controls: [button] + }; const parentTab = { - id: "CustomChartTab", - groups: [parentGroup] - }; + id: "CustomChartTab", + groups: [parentGroup] + }; const ribbonUpdater = {tabs: [parentTab]}; Office.ribbon.requestUpdate(ribbonUpdater); } @@ -198,17 +198,17 @@ The following example shows a function that disables a button and records the bu ```javascript function disableChartFormat() { const button = { - id: "ChartFormatButton", - enabled: false - }; + id: "ChartFormatButton", + enabled: false + }; const parentGroup = { - id: "MyGroup", - controls: [button] - }; + id: "MyGroup", + controls: [button] + }; const parentTab = { - id: "CustomChartTab", - groups: [parentGroup] - }; + id: "CustomChartTab", + groups: [parentGroup] + }; const ribbonUpdater = {tabs: [parentTab]}; Office.ribbon.requestUpdate(ribbonUpdater); @@ -240,17 +240,17 @@ In some scenarios, Office is unable to update the ribbon and will return an erro function disableChartFormat() { try { const button = { - id: "ChartFormatButton", - enabled: false - }; + id: "ChartFormatButton", + enabled: false + }; const parentGroup = { - id: "MyGroup", - controls: [button] - }; + id: "MyGroup", + controls: [button] + }; const parentTab = { - id: "CustomChartTab", - groups: [parentGroup] - }; + id: "CustomChartTab", + groups: [parentGroup] + }; const ribbonUpdater = {tabs: [parentTab]}; Office.ribbon.requestUpdate(ribbonUpdater); diff --git a/docs/develop/automatically-open-a-task-pane-with-a-document.md b/docs/develop/automatically-open-a-task-pane-with-a-document.md index 3e0da3ef7f..a88d3114cf 100644 --- a/docs/develop/automatically-open-a-task-pane-with-a-document.md +++ b/docs/develop/automatically-open-a-task-pane-with-a-document.md @@ -89,7 +89,7 @@ The following example shows a "view" value set to "Office.AutoShowTaskpaneWithDo To specify the task pane to open automatically, set the [TaskpaneId](/javascript/api/manifest/action#taskpaneid) value to **Office.AutoShowTaskpaneWithDocument**. You can only set this value on one task pane. If you set this value on multiple task panes, the first occurrence of the value will be recognized and the others will be ignored. -The following example shows the TaskPaneId value set to Office.AutoShowTaskpaneWithDocument. +The following example shows the **\** value set to **Office.AutoShowTaskpaneWithDocument**. ```xml diff --git a/docs/develop/dialog-api-in-office-add-ins.md b/docs/develop/dialog-api-in-office-add-ins.md index e3bb83602a..e7fc3a3a43 100644 --- a/docs/develop/dialog-api-in-office-add-ins.md +++ b/docs/develop/dialog-api-in-office-add-ins.md @@ -330,7 +330,7 @@ Because you can make multiple `messageChild` calls from the host page, but you h > In some situations, the `messageChild` API, which is a part of the [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets), may not be supported. For example, `messageChild` isn't supported in volume-licensed perpetual Outlook 2016 and volume-licensed perpetual Outlook 2019. Some alternative ways for parent-to-dialog-box messaging are described in [Alternative ways of passing messages to a dialog box from its host page](parent-to-dialog.md). > [!IMPORTANT] -> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the add-in manifest. You will have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). Support for manifest requirements is under development. +> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the add-in manifest. You'll have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). Support for manifest requirements is under development. ### Cross-domain messaging to the dialog runtime @@ -351,11 +351,11 @@ If the message doesn't include sensitive data, you can set the `targetOrigin` to dialog.messageChild(messageToDialog, { targetOrigin: "*" }); ``` -The add-in's manifest specifies trusted domains. In the unified manifest for Microsoft 365, this is specified in the "validDomains" property. In the add-only manifest, this is specified in the **\** element. +The add-in's manifest specifies trusted domains. In the unified manifest for Microsoft 365, this is specified in the "validDomains" property. In the add-in only manifest, this is specified in the **\** element. [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] -But the runtime that is hosting the dialog can't access the manifest and thereby determine whether the domain *from which the message comes* is trusted, you must use the `DialogParentMessageReceived` handler to determine this. The object that is passed to the handler contains the domain that is currently hosted in the parent as its `origin` property. The following is an example of how to use the property. +But the runtime that's hosting the dialog can't access the manifest and thereby determine whether the domain *from which the message comes* is trusted, you must use the `DialogParentMessageReceived` handler to determine this. The object that's passed to the handler contains the domain that's currently hosted in the parent as its `origin` property. The following is an example of how to use the property. ```javascript function onMessageFromParent(arg) { diff --git a/docs/develop/show-hide-add-in.md b/docs/develop/show-hide-add-in.md index 55ea6a0033..f313fa11b1 100644 --- a/docs/develop/show-hide-add-in.md +++ b/docs/develop/show-hide-add-in.md @@ -36,7 +36,7 @@ The previous code is a handler that is registered for the [Office.Worksheet.onDe ## Additional details on showing the task pane -When you call `Office.addin.showAsTaskpane()`, Office will display in a task pane the file that you specified in the manifest. The configuration depends on what type of manifest you are using. +When you call `Office.addin.showAsTaskpane()`, Office will display in a task pane the file that you specified in the manifest. The configuration depends on what type of manifest you're using. - **Unified manifest for Microsoft 365**: The URL of the file is assigned as the value of a "runtimes.code.page" property of the runtime object which has an action object of type "openPage". diff --git a/docs/includes/unified-manifest-support-note.md b/docs/includes/unified-manifest-support-note.md index 2810e966df..787a385778 100644 --- a/docs/includes/unified-manifest-support-note.md +++ b/docs/includes/unified-manifest-support-note.md @@ -1,2 +1,2 @@ > [!NOTE] -> The [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) can be used in production Outlook add-ins. It is available only as a preview for Excel, PowerPoint, and Word add-ins. \ No newline at end of file +> The [unified manifest for Microsoft 365](../develop/unified-manifest-overview.md) can be used in production Outlook add-ins. It's available only as a preview for Excel, PowerPoint, and Word add-ins. \ No newline at end of file From cfcd9dd82ff09d81b4ecfb8f06062dfdbc17be78 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Sat, 7 Sep 2024 12:52:48 -0700 Subject: [PATCH 7/9] review changes --- docs/design/contextual-tabs.md | 5 +++-- docs/design/disable-add-in-commands.md | 9 +++++---- .../automatically-open-a-task-pane-with-a-document.md | 2 +- docs/develop/automatically-open-on-installation.md | 2 +- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/design/contextual-tabs.md b/docs/design/contextual-tabs.md index fcb29eb333..5faa9e9dab 100644 --- a/docs/design/contextual-tabs.md +++ b/docs/design/contextual-tabs.md @@ -11,7 +11,7 @@ ms.localizationpriority: medium A contextual tab is a hidden tab control in the Office ribbon that's displayed in the tab row when a specified event occurs in the Office document. For example, the **Table Design** tab that appears on the Excel ribbon when a table is selected. You include custom contextual tabs in your Office Add-in and specify when they're visible or hidden, by creating event handlers that change the visibility. (However, custom contextual tabs don't respond to focus changes.) > [!NOTE] -> This article assumes that you're familiar with the following documentation. Please review it if you haven't worked with Add-in Commands (custom menu items and ribbon buttons) recently. +> This article assumes that you're familiar with the following documentation. Please review it if you haven't worked with add-in commands (custom menu items and ribbon buttons) recently. > > - [Basic concepts for Add-in Commands](add-in-commands.md) @@ -537,7 +537,7 @@ Begin by defining a custom core tab (that is, *noncontextual* custom tab) in the - 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. - 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. -The following is an example. Note that "MyButton" 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. +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. ```json "extensions": [ @@ -556,6 +556,7 @@ The following is an example. Note that "MyButton" will appear on the custom core ... "controls": [ { + "id": "Contoso.MyButton1", ... "overriddenByRibbonApi": true } diff --git a/docs/design/disable-add-in-commands.md b/docs/design/disable-add-in-commands.md index 33963aa83f..d5ccef95cc 100644 --- a/docs/design/disable-add-in-commands.md +++ b/docs/design/disable-add-in-commands.md @@ -8,12 +8,12 @@ ms.localizationpriority: medium # Enable and Disable Add-in Commands -When some functionality in your add-in should only be available in certain contexts, you can programmatically enable or disable your custom Add-in Commands. For example, a function that changes the header of a table should only be enabled when the cursor is in a table. +When some functionality in your add-in should only be available in certain contexts, you can programmatically enable or disable your custom add-in commands. For example, a function that changes the header of a table should only be enabled when the cursor is in a table. You can also specify whether the command is enabled or disabled when the Office client application opens. > [!NOTE] -> This article assumes that you're familiar with the [basic concepts for Add-in Commands](add-in-commands.md). Please review it if you haven't worked with Add-in Commands (custom menu items and ribbon buttons) recently. +> This article assumes that you're familiar with the [basic concepts for Add-in Commands](add-in-commands.md). Please review it if you haven't worked with add-in commands (custom menu items and ribbon buttons) recently. ## Office application and platform support @@ -25,7 +25,7 @@ The APIs and manifest markup described in this article require that the add-in's ## Set the default state to disabled -By default, any Add-in Command is enabled when the Office application launches. If you want a custom button or menu item to be disabled when the Office application launches, you specify this in the manifest. The process depends on which type of manifest your add-in uses. +By default, any add-in command is enabled when the Office application launches. If you want a custom button or menu item to be disabled when the Office application launches, you specify this in the manifest. The process depends on which type of manifest your add-in uses. # [Unified manifest for Microsoft 365](#tab/jsonmanifest) @@ -50,6 +50,7 @@ Just add an "enabled" property with the value `false` to the control or menu ite ... "controls": [ { + "id": "Contoso.MyButton1", ... "enabled": false } @@ -94,7 +95,7 @@ Just add an [Enabled](/javascript/api/manifest/enabled) element (with the value ## Change the state programmatically -The essential steps to changing the enabled status of an Add-in Command are: +The essential steps to changing the enabled status of an add-in command are: 1. Create a [RibbonUpdaterData](/javascript/api/office/office.ribbonupdaterdata) object that (1) specifies the command, and its parent group and tab, by their IDs as declared in the manifest; and (2) specifies the enabled or disabled state of the command. 1. Pass the **RibbonUpdaterData** object to the [Office.ribbon.requestUpdate()](/javascript/api/office/office.ribbon?view=common-js&preserve-view=true#office-office-ribbon-requestupdate-member(1)) method. diff --git a/docs/develop/automatically-open-a-task-pane-with-a-document.md b/docs/develop/automatically-open-a-task-pane-with-a-document.md index a88d3114cf..b0379389cf 100644 --- a/docs/develop/automatically-open-a-task-pane-with-a-document.md +++ b/docs/develop/automatically-open-a-task-pane-with-a-document.md @@ -63,7 +63,7 @@ Configure the manifest to specify the task pane page that should open automatica [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] -To specify the task pane to open automatically, find the runtime object in the "runtimes" array whose "code.page" property is set to the URL of the page that you want to open automatically. Ensure that the "actions" array in this same runtime object has at least one action whose "type" value is "openPage". Add a "view" property to this action object and set it to "Office.AutoShowTaskpaneWithDocument". You can only set this value on one action object and it must an action of type "openPage". If you set this value on multiple actions, the first occurrence of the value will be recognized and the others will be ignored. +To specify the task pane to open automatically, find the runtime object in the "runtimes" array whose "code.page" property is set to the URL of the page that you want to open automatically. Ensure that the "actions" array in this same runtime object has at least one action whose "type" value is "openPage". Add a "view" property to this action object and set it to "Office.AutoShowTaskpaneWithDocument". You can only set this value on one action object and it must be an action of type "openPage". If you set this value on multiple actions, the first occurrence of the value will be recognized and the others will be ignored. The following example shows a "view" value set to "Office.AutoShowTaskpaneWithDocument". diff --git a/docs/develop/automatically-open-on-installation.md b/docs/develop/automatically-open-on-installation.md index d22b31ba74..7b72fd06cf 100644 --- a/docs/develop/automatically-open-on-installation.md +++ b/docs/develop/automatically-open-on-installation.md @@ -38,7 +38,7 @@ The process for specifying the default task pane depends on the type of manifest [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)] -To specify the default task pane, find the runtime object in the "runtimes" array whose "code.page" property is set to the URL of the page that you want to be the default. Ensure that the "actions" array in this same runtime object has at least one action whose "type" value is "openPage". Add a "view" property to this action object and set it to "Office.AutoShowTaskpaneWithDocument". You can only set this value on one action object and it must an action of type "openPage". If you set this value on multiple actions, the first occurrence of the value will be recognized as the default and the others will be ignored. +To specify the default task pane, find the runtime object in the "runtimes" array whose "code.page" property is set to the URL of the page that you want to be the default. Ensure that the "actions" array in this same runtime object has at least one action whose "type" value is "openPage". Add a "view" property to this action object and set it to "Office.AutoShowTaskpaneWithDocument". You can only set this value on one action object and it must be an action of type "openPage". If you set this value on multiple actions, the first occurrence of the value will be recognized as the default and the others will be ignored. The following example shows a "view" value set to "Office.AutoShowTaskpaneWithDocument". From 95b7e16808e3cf4f7de951d94a0ff793638231d7 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Mon, 7 Oct 2024 14:37:03 -0700 Subject: [PATCH 8/9] Update dialog-api-in-office-add-ins.md --- docs/develop/dialog-api-in-office-add-ins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/dialog-api-in-office-add-ins.md b/docs/develop/dialog-api-in-office-add-ins.md index e7fc3a3a43..5f7c7e180b 100644 --- a/docs/develop/dialog-api-in-office-add-ins.md +++ b/docs/develop/dialog-api-in-office-add-ins.md @@ -330,7 +330,7 @@ Because you can make multiple `messageChild` calls from the host page, but you h > In some situations, the `messageChild` API, which is a part of the [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets), may not be supported. For example, `messageChild` isn't supported in volume-licensed perpetual Outlook 2016 and volume-licensed perpetual Outlook 2019. Some alternative ways for parent-to-dialog-box messaging are described in [Alternative ways of passing messages to a dialog box from its host page](parent-to-dialog.md). > [!IMPORTANT] -> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the add-in manifest. You'll have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). Support for manifest requirements is under development. +> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the add-in manifest. You'll have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Check for API availability at runtime](specify-api-requirements-runtime.md). Support for manifest requirements is under development. ### Cross-domain messaging to the dialog runtime From 30254d471897309b1d29dd2593c08dbdfc04b829 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Mon, 7 Oct 2024 14:44:05 -0700 Subject: [PATCH 9/9] Update contextual-tabs.md --- docs/design/contextual-tabs.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/design/contextual-tabs.md b/docs/design/contextual-tabs.md index 5faa9e9dab..4a204dd5d6 100644 --- a/docs/design/contextual-tabs.md +++ b/docs/design/contextual-tabs.md @@ -28,7 +28,8 @@ A contextual tab is a hidden tab control in the Office ribbon that's displayed i > - [RibbonApi 1.2](/javascript/api/requirement-sets/common/ribbon-api-requirement-sets) > - [SharedRuntime 1.1](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets) > -> You can use the runtime checks in your code to test whether the user's host and platform combination supports these requirement sets as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). (The technique of specifying the requirement sets in the manifest, which is also described in that article, does not currently work for RibbonApi 1.2.) Alternatively, you can [implement an alternate UI experience when custom contextual tabs are not supported](#implement-an-alternate-ui-experience-when-custom-contextual-tabs-arent-supported). +> [!TIP] +> Use the runtime checks in your code to test whether the user's host and platform combination supports these requirement sets as described in [Check for API availability at runtime](../develop/specify-api-requirements-runtime.md). (The technique of specifying the requirement sets in the manifest, which is also described in that article, doesn't currently work for RibbonApi 1.2.) Alternatively, you can [implement an alternate UI experience when custom contextual tabs aren't supported](#implement-an-alternate-ui-experience-when-custom-contextual-tabs-arent-supported). ## Behavior of custom contextual tabs