From 0e45d553cb8baac7798c849f0223296894a55cde Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Thu, 3 Oct 2024 15:50:10 -0700 Subject: [PATCH 1/6] [All Hosts] (manifest) update tech background articles for unified manifest --- .../specify-api-requirements-runtime.md | 84 +++++++++ ...fice-hosts-and-api-requirements-unified.md | 166 ++++++++++++++++++ ...ecify-office-hosts-and-api-requirements.md | 94 ++-------- docs/toc.yml | 8 +- 4 files changed, 274 insertions(+), 78 deletions(-) create mode 100644 docs/develop/specify-api-requirements-runtime.md create mode 100644 docs/develop/specify-office-hosts-and-api-requirements-unified.md diff --git a/docs/develop/specify-api-requirements-runtime.md b/docs/develop/specify-api-requirements-runtime.md new file mode 100644 index 0000000000..7153954694 --- /dev/null +++ b/docs/develop/specify-api-requirements-runtime.md @@ -0,0 +1,84 @@ +--- +title: Check for API availability at runtime +description: Learn how to verify at runtime that the Office application supports your add-ins API calls. +ms.topic: best-practice +ms.date: 11/04/2024 +ms.localizationpriority: medium +--- + +# Check for API availability at runtime + +If your add-in uses a specific extensibility feature for some of its functionality but has other useful functionality that doesn't require the extensibility feature, you should design the add-in so that it's installable on platform and Office version combinations that don't support the extensibility feature. It can provide a valuable, albeit diminished, experience on those combinations. + +When the difference in the two experiences is consists entirely of differences in the Office JavaScript Library APIs that are called, and not in any features that are configured in the manifest, then you test at runtime to discover whether the user's Office supports an [API requirement set](office-versions-and-requirement-sets.md). You can also [test at runtime whether APIs that are not in a set are supported](#check-for-setless-api-support). + +> [!NOTE] +> To provide alternate experiences with features that require manifest configuration, follow the guidance in [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md) or [Specify Office applications and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md). + +## Check for requirement set support + +The [isSetSupported](/javascript/api/office/office.requirementsetsupport#office-office-requirementsetsupport-issetsupported-member(1)) method is used to check for requirement set support. Pass the requirement set's name and the minimum version as parameters. If the requirement set is supported, `isSetSupported` returns `true`. The following code shows an example. + +```js +if (Office.context.requirements.isSetSupported("WordApi", "1.2")) +{ + // Code that uses API members from the WordApi 1.2 requirement set. +} else { + // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2). +} +``` + +About this code, note: + +- The first parameter is required. It's a string that represents the name of the requirement set. For more information about available requirement sets, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). +- The second parameter is optional. It's a string that specifies the minimum requirement set version that the Office application must support in order for the code within the `if` statement to run (e.g., "1.9"). If not used, version "1.1" is assumed. + +> [!WARNING] +> When calling the `isSetSupported` method, the value of the second parameter (if specified) should be a string not a number. The JavaScript parser cannot differentiate between numeric values such as 1.1 and 1.10, whereas it can for string values such as "1.1" and "1.10". + +The following table shows the requirement set names for the application specific API models. + +|Office application|RequirementSetName| +|---|---| +|Excel|ExcelApi| +|OneNote|OneNoteApi| +|Outlook|Mailbox| +|PowerPoint|PowerPointApi| +|Word|WordApi| + +The following is an example of using the method with one of the Common API model requirement sets. + +```js +if (Office.context.requirements.isSetSupported('CustomXmlParts')) +{ + // Run code that uses API members from the CustomXmlParts requirement set. +} +else +{ + // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set. +} +``` + +> [!NOTE] +> The `isSetSupported` method and the requirement sets for these applications are available in the latest Office.js file on the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions if you are using an old version of the library in which `isSetSupported` is undefined. For more information, see [Use the latest Office JavaScript API library](#use-the-latest-office-javascript-api-library). + +## Check for setless API support + +When your add-in depends on a method that isn't part of a requirement set, called a setless API, use a runtime check to determine whether the method is supported by the Office application, as shown in the following code example. For a complete list of methods that don't belong to a requirement set, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets#methods-that-arent-part-of-a-requirement-set). + +> [!NOTE] +> We recommend that you limit the use of this type of runtime check in your add-in's code. + +The following code example checks whether the Office application supports `document.setSelectedDataAsync`. + +```js +if (Office.context.document.setSelectedDataAsync) +{ + // Run code that uses `document.setSelectedDataAsync`. +} +``` + +## See also +- [Office requirement sets availability](office-versions-and-requirement-sets.md#office-requirement-sets-availability) +- [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md) +- [Specify Office hosts and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md) diff --git a/docs/develop/specify-office-hosts-and-api-requirements-unified.md b/docs/develop/specify-office-hosts-and-api-requirements-unified.md new file mode 100644 index 0000000000..db684eac37 --- /dev/null +++ b/docs/develop/specify-office-hosts-and-api-requirements-unified.md @@ -0,0 +1,166 @@ +--- +title: Specify Office hosts and API requirements with the unified manifest +description: Learn how to specify in the unified manifest the Office applications and API requirements for your add-in to work as expected. +ms.topic: best-practice +ms.date: 11/04/2024 +ms.localizationpriority: medium +--- + +# Specify Office applications and API requirements with the unified manifest + +> [!NOTE] +> For information about specifying requirements with the add-in only manifest, see [Specify Office hosts and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md). + +Your Office Add-in might depend on a specific Office application (also called an Office host) or on specific members of the Office JavaScript Library (office.js). For example, your add-in might: + +- Run in a single Office application (e.g., Word or Excel), or several applications. +- Make use of Office JavaScript APIs that are only available in some versions of Office. For example, the volume-licensed perpetual version of Excel 2016 doesn't support all Excel-related APIs in the Office JavaScript library. +- Be designed for use only in a mobile form factor. + +In these situations, you need to ensure that your add-in is never installed on Office applications or Office versions in which it cannot run. + +There are also scenarios in which you want to control which features of your add-in are visible to users based on their Office application and Office version. Three examples are: + +- Your add-in has features that are useful in both Word and PowerPoint, such as text manipulation, but it has some additional features that only make sense in PowerPoint, such as slide management features. You need to hide the PowerPoint-only features when the add-in is running in Word. +- Your add-in has a feature that requires an Office JavaScript API method that is supported in some versions of an Office application, such as Microsoft 365 subscription Excel, but isn't supported in others, such as volume-licensed perpetual Excel 2016. But your add-in has other features that require only Office JavaScript API methods that *are* supported in volume-licensed perpetual Excel 2016. In this scenario, you need the add-in to be installable on that version of Excel 2016, but the feature that requires the unsupported method should be hidden from those users. +- Your add-in has features that are supported in desktop Office, but not in mobile Office. + +This article helps you understand how to ensure that your add-in works as expected and reaches the broadest audience possible. + +> [!NOTE] +> For a high-level view of where Office Add-ins are currently supported, see the [Office client application and platform availability for Office Add-ins](/javascript/api/requirement-sets) page. + +> [!TIP] +> Many of the tasks described in this article are done for you, in whole or in part, when you create your add-in project with a tool, such as the [Yeoman generator for Office Add-ins](yeoman-generator-overview.md) or one of the Office Add-in templates in Visual Studio. In such cases, please interpret the task as meaning that you should verify that it has been done. + +## Use the latest Office JavaScript API library + +Your add-in should load the most current version of the Office JavaScript API library from the content delivery network (CDN). To do this, be sure you have the following ` +``` + +## Specify which Office applications can host your add-in + +To specify the Office applications on which your add-in can be installed, use the "extensions.requirements.scopes" array. Specify any subset of "mail", "workbook", "document", and "presentation". The following table shows which Office application and platform combinations correspond to these values. It also shows what kind of add-in can be installed for each scope. + + +| Name | Office client applications | Available add-in types | +|:--------------|:-----------------------------------------------|:-----------------------| +| document | Word on the web, Windows, Mac, iPad | Task pane | +| mail | Outlook on the web, Windows ([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) and classic), Mac, Android, iOS | Mail | +| presentation | PowerPoint on the web, Windows, Mac, iPad | Task pane, Content | +| workbook | Excel on the web, Windows, Mac, iPad | Task pane, Content | + +> [!NOTE] +> Content add-ins have an "extensions.contentRuntimes" property. They cannot have an "extensions.runtimes" property so they cannot be combined with a Task pane or Mail add-in. For more information about Content add-ins, see [Content Office Add-ins](../design/content-add-ins.md). + +For example, the following JSON specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but cannot be installed on any other Office application. + +```json +"extensions": [ + { + "requirements": { + "scopes": [ "workbook" ], + }, + ... + } +] +``` + +> [!NOTE] +> Office applications are supported on different platforms and run on desktops, web browsers, tablets, and mobile devices. You usually can't specify which platform can be used to run your add-in. For example, if you specify "workbook", both Excel on the web and on Windows can be used to run your add-in. However, if you specify "mail", your add-in won't run on Outlook mobile clients unless you define the [mobile extension point](/javascript/api/manifest/extensionpoint#mobilemessagereadcommandsurface). + +## Specify which Office APIs your add-in needs + +You can't explicitly specify the Office versions and builds or the platforms on which your add-in should be installable, and you wouldn't want to because you would have to revise your manifest whenever support for the add-in features that your add-in uses is extended to a new version or platform. Instead, specify in the manifest the APIs that your add-in needs. Office prevents the add-in from being installed on combinations of Office version and platform that don't support the APIs and ensures that the add-in won't appear in **My Add-ins**. + +> [!IMPORTANT] +> Only use the "requirements" property that is a direct child of "extensions" to specify the API members that your add-in must have to be of any significant value at all. If your add-in uses an API for some features but has other useful features that don't require the API, you should design the add-in so that it's installable on platform and Office version combinations that don't support the API but provides a diminished experience on those combinations. For this purpose, use "requirements" properties that aren't direct children of "extensions". For more information, see [Design for alternate experiences](#design-for-alternate-experiences). + +### Requirement sets + +To simplify the process of specifying the APIs that your add-in needs, Office groups most APIs together in [requirement sets](office-versions-and-requirement-sets.md). The APIs in the [Common API Object Model](understanding-the-javascript-api-for-office.md#api-models) are grouped by the development feature that they support. For example, all the APIs connected to table bindings are in the requirement set called "TableBindings 1.1". The APIs in the [Application specific object models](understanding-the-javascript-api-for-office.md#api-models) are grouped by when they were released for use in production add-ins. + +Requirement sets are versioned. For example, the APIs that support [Dialog Boxes](../develop/dialog-api-in-office-add-ins.md) are in the requirement set DialogApi 1.1. When additional APIs that enable messaging from a task pane to a dialog were released, they were grouped into DialogApi 1.2, along with all the APIs in DialogApi 1.1. *Each version of a requirement set is a superset of all earlier versions.* + +Requirement set support varies by Office application, the version of the Office application, and the platform on which it is running. For example, DialogApi 1.2 isn't supported on volume-licensed perpetual versions of Office before Office 2021, but DialogApi 1.1 is supported on all perpetual versions back to Office 2016. You want your add-in to be installable on every combination of platform and Office version that supports the APIs that it uses, so you should always specify in the manifest the *minimum* version of each requirement set that your add-in requires. Details about how to do this are later in this article. + +> [!TIP] +> For more information about requirement set versioning, see [Office requirement sets availability](office-versions-and-requirement-sets.md#office-requirement-sets-availability), and for the complete lists of requirement sets and information about the APIs in each, start with [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). The reference topics for most Office.js APIs also specify the requirement set they belong to (if any). + +### extensions.requirements.capabilities property + +Use the "requirements.capabilities" property to specify the minimum requirement sets that must be supported by the Office application to install your add-in. If the Office application or platform doesn't support the requirement sets or API members specified in the "requirements.capabilities" property, the add-in won't run in that application or platform, and won't display in **My Add-ins**. + +> [!TIP] +> All APIs in the application specific models are in requirement sets, but some of those in the Common API model aren't. If your add-in requires an API that isn't in any requirement set, you can implement a runtime check for the availability of the API and display a message to the add-in's users if it isn't supported. For more information, see [Check for API availability at runtime](specify-api-requirements-runtime.md). + +The following code example shows how to configure an add-in that is installable in all Office application and platform combinations that support the following: + +- `TableBindings` requirement set, which has a minimum version of "1.1". +- `OOXML` requirement set, which has a minimum version of "1.1". + +```json +"extensions": [ + { + "requirements": { + "capabilities": [ + { + "name": "TableBindings", + "minVersion": "1.1" + }, + { + "name": "OOXML", + "minVersion": "1.1" + } + ], + }, + ... + } +] +``` + +> [!TIP] +> For more information and another example of using the "extensions.requirements" property, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- extensions.requirements](/develop/requirements-property-unified-manifest.md#extensionsrequirements). + +### Specify the form factors on which your add-in can be installed + +For an Outlook add-in is installable on desktop, you can also specify whether the add-in should be installable on desktop (includes tablets) or mobile form factors. Use the "extensions.requirements.formFactors" property. The following example show how to make the Outlook add-in installable on both form factors. + +```json +"extensions": [ + { + "requirements": { + ... + "formFactors": [ + "desktop", + "mobile" + ] + }, + ... + } +] +``` + +## Design for alternate experiences + +The extensibility features that the Office Add-in platform provides can be usefully divided into three kinds: + +- Extensibility features that are available immediately after the add-in is installed. An example of this kind of feature is [Add-in Commands](../design/add-in-commands.md), which are custom ribbon buttons and menus. +- Extensibility features that are available only when the add-in is running and that are implemented with Office.js JavaScript APIs; for example, [Dialog Boxes](../develop/dialog-api-in-office-add-ins.md). +- Extensibility features that are available only at runtime but are implemented with a combination of Office.js JavaScript and manifest configuration. Examples of these are [Excel custom functions](../excel/custom-functions-overview.md), [single sign-on](sso-in-office-add-ins.md), and [custom contextual tabs](../design/contextual-tabs.md). + +If your add-in uses a specific extensibility feature for some of its functionality but has other useful functionality that doesn't require the extensibility feature, you should design the add-in so that it's installable on platform and Office version combinations that don't support the extensibility feature. It can provide a valuable, albeit diminished, experience on those combinations. + +You implement this design differently depending on how the extensibility feature is implemented: + +- For features implemented entirely with JavaScript, see [Check for API availability at runtime](specify-api-requirements-runtime.md). +- For features that require you to configure the manifest, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- Filter features](/develop/requirements-property-unified-manifest.md#filter-features). + +## See also + +- [Office Add-ins manifest](add-in-manifests.md) +- [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets) +- [Specify Office Add-in requirements in the unified manifest for Microsoft 365](/develop/requirements-property-unified-manifest.md). diff --git a/docs/develop/specify-office-hosts-and-api-requirements.md b/docs/develop/specify-office-hosts-and-api-requirements.md index b88f0ba38b..4f6c419ee8 100644 --- a/docs/develop/specify-office-hosts-and-api-requirements.md +++ b/docs/develop/specify-office-hosts-and-api-requirements.md @@ -1,14 +1,17 @@ --- -title: Specify Office hosts and API requirements +title: Specify Office hosts and API requirements with the add-in only manifest description: Learn how to specify Office applications and API requirements for your add-in to work as expected. ms.topic: best-practice -ms.date: 02/29/2024 +ms.date: 11/04/2024 ms.localizationpriority: medium --- -# Specify Office applications and API requirements +# Specify Office applications and API requirements with the add-in only manifest -Your Office Add-in might depend on a specific Office application (also called an Office host) or on specific members of the Office JavaScript API (office.js). For example, your add-in might: +> [!NOTE] +> For information about specifying requirements with the [unified manifest for Microsoft 365](unified-manifest-overview.md), see [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md). + +Your Office Add-in might depend on a specific Office application (also called an Office host) or on specific members of the Office JavaScript Library (office.js). For example, your add-in might: - Run in a single Office application (e.g., Word or Excel), or several applications. - Make use of Office JavaScript APIs that are only available in some versions of Office. For example, the volume-licensed perpetual version of Excel 2016 doesn't support all Excel-related APIs in the Office JavaScript library. @@ -30,17 +33,17 @@ This article helps you understand which options you should choose to ensure that ## Use the latest Office JavaScript API library -Your add-in should load the most current version of the Office JavaScript API library from the content delivery network (CDN). To do this, be sure you have the following `script` tag in the first HTML file your add-in opens. Using `/1/` in the CDN URL ensures that you reference the most recent version of Office.js. +Your add-in should load the most current version of the Office JavaScript API library from the content delivery network (CDN). To do this, be sure you have the following ` + ``` ## Specify which Office applications can host your add-in By default, an add-in is installable in all Office applications supported by the specified add-in type (that is, Mail, Task pane, or Content). For example, a task pane add-in is installable by default on Access, Excel, OneNote, PowerPoint, Project, and Word. -To ensure that your add-in is installable in a subset of Office applications, use the [Hosts](/javascript/api/manifest/hosts) and [Host](/javascript/api/manifest/host) elements in the manifest. +To ensure that your add-in is installable in only a subset of Office applications, use the [Hosts](/javascript/api/manifest/hosts) and [Host](/javascript/api/manifest/host) elements in the add-in only manifest. For example, the following **\** and **\** declaration specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but cannot be installed on any other Office application. @@ -66,7 +69,7 @@ The **\** element can contain one or more **\** elements. There s > Office applications are supported on different platforms and run on desktops, web browsers, tablets, and mobile devices. You usually can't specify which platform can be used to run your add-in. For example, if you specify `Workbook`, both Excel on the web and on Windows can be used to run your add-in. However, if you specify `Mailbox`, your add-in won't run on Outlook mobile clients unless you define the [mobile extension point](/javascript/api/manifest/extensionpoint#mobilemessagereadcommandsurface). > [!NOTE] -> It isn't possible for an add-in manifest to apply to more than one type: Mail, Task pane, or Content. This means that if you want your add-in to be installable on Outlook and on one of the other Office applications, you must create *two* add-ins, one with a Mail type manifest and the other with a Task pane or Content type manifest. +> It isn't possible for an add-in only manifest to apply to more than one type: Mail, Task pane, or Content. This means that if you want your add-in to be installable on Outlook and on one of the other Office applications, you must create *two* add-ins, one with a Mail type manifest and the other with a Task pane or Content type manifest. ## Specify which Office versions and platforms can host your add-in @@ -77,7 +80,7 @@ You can't explicitly specify the Office versions and builds or the platforms on ### Requirement sets -To simplify the process of specifying the APIs that your add-in needs, Office groups most APIs together in *requirement sets*. The APIs in the [Common API Object Model](understanding-the-javascript-api-for-office.md#api-models) are grouped by the development feature that they support. For example, all the APIs connected to table bindings are in the requirement set called "TableBindings 1.1". The APIs in the [Application specific object models](understanding-the-javascript-api-for-office.md#api-models) are grouped by when they were released for use in production add-ins. +To simplify the process of specifying the APIs that your add-in needs, Office groups most APIs together in [requirement sets](office-versions-and-requirement-sets.md). The APIs in the [Common API Object Model](understanding-the-javascript-api-for-office.md#api-models) are grouped by the development feature that they support. For example, all the APIs connected to table bindings are in the requirement set called "TableBindings 1.1". The APIs in the [Application specific object models](understanding-the-javascript-api-for-office.md#api-models) are grouped by when they were released for use in production add-ins. Requirement sets are versioned. For example, the APIs that support [Dialog Boxes](../develop/dialog-api-in-office-add-ins.md) are in the requirement set DialogApi 1.1. When additional APIs that enable messaging from a task pane to a dialog were released, they were grouped into DialogApi 1.2, along with all the APIs in DialogApi 1.1. *Each version of a requirement set is a superset of all earlier versions.* @@ -89,13 +92,11 @@ Requirement set support varies by Office application, the version of the Office > [!NOTE] > Some requirement sets also have manifest elements associated with them. See [Specifying requirements in a VersionOverrides element](#specify-requirements-in-a-versionoverrides-element) for information about when this fact is relevant to your add-in design. -#### APIs not in a requirement set - -All APIs in the application specific models are in requirement sets, but some of those in the Common API model are not. There is also a way that you can specify one of these setless APIs in the manifest when your add-in requires one. Details are later in this article. - ### Requirements element -Use the [Requirements](/javascript/api/manifest/requirements) element and its child elements [Sets](/javascript/api/manifest/sets) and [Methods](/javascript/api/manifest/methods) to specify the minimum requirement sets or API members that must be supported by the Office application to install your add-in. +Use the [Requirements](/javascript/api/manifest/requirements) element and its child element [Sets](/javascript/api/manifest/sets) to specify the minimum requirement sets that must be supported by the Office application to install your add-in. + +All APIs in the application specific models are in requirement sets, but some of those in the Common API model are not. Use the [Methods](/javascript/api/manifest/methods) to specify the setless API members that your add-in requires. You can't use the **\** element with Outlook add-ins. If the Office application or platform doesn't support the requirement sets or API members specified in the **\** element, the add-in won't run in that application or platform, and won't display in **My Add-ins**. @@ -144,70 +145,9 @@ If your add-in uses a specific extensibility feature for some of its functionali You implement this design differently depending on how the extensibility feature is implemented: -- For features implemented entirely with JavaScript, see [Runtime checks for method and requirement set support](#runtime-checks-for-method-and-requirement-set-support). +- For features implemented entirely with JavaScript, see [Check for API availability at runtime](specify-api-requirements-runtime.md). - For features that require you to configure a **\** element, see [Specifying requirements in a VersionOverrides element](#specify-requirements-in-a-versionoverrides-element). -### Runtime checks for method and requirement set support - -You test at runtime to discover whether the user's Office supports a requirement set with the [isSetSupported](/javascript/api/office/office.requirementsetsupport#office-office-requirementsetsupport-issetsupported-member(1)) method. Pass the requirement set's name and the minimum version as parameters. If the requirement set is supported, `isSetSupported` returns `true`. The following code shows an example. - -```js -if (Office.context.requirements.isSetSupported('WordApi', '1.2')) -{ - // Code that uses API members from the WordApi 1.2 requirement set. -} else { - // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2). -} -``` - -About this code, note: - -- The first parameter is required. It's a string that represents the name of the requirement set. For more information about available requirement sets, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). -- The second parameter is optional. It's a string that specifies the minimum requirement set version that the Office application must support in order for the code within the `if` statement to run (e.g., "**1.9**"). If not used, version "1.1" is assumed. - -> [!WARNING] -> When calling the `isSetSupported` method, the value of the second parameter (if specified) should be a string not a number. The JavaScript parser cannot differentiate between numeric values such as 1.1 and 1.10, whereas it can for string values such as "1.1" and "1.10". - -The following table shows the requirement set names for the application specific API models. - -|Office application|RequirementSetName| -|---|---| -|Excel|ExcelApi| -|OneNote|OneNoteApi| -|Outlook|Mailbox| -|PowerPoint|PowerPointApi| -|Word|WordApi| - -The following is an example of using the method with one of the Common API model requirement sets. - -```js -if (Office.context.requirements.isSetSupported('CustomXmlParts')) -{ - // Run code that uses API members from the CustomXmlParts requirement set. -} -else -{ - // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set. -} -``` - -> [!NOTE] -> The `isSetSupported` method and the requirement sets for these applications are available in the latest Office.js file on the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions if you are using an old version of the library in which `isSetSupported` is undefined. For more information, see [Use the latest Office JavaScript API library](#use-the-latest-office-javascript-api-library). - -When your add-in depends on a method that isn't part of a requirement set, use the runtime check to determine whether the method is supported by the Office application, as shown in the following code example. For a complete list of methods that don't belong to a requirement set, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets#methods-that-arent-part-of-a-requirement-set). - -> [!NOTE] -> We recommend that you limit the use of this type of runtime check in your add-in's code. - -The following code example checks whether the Office application supports `document.setSelectedDataAsync`. - -```js -if (Office.context.document.setSelectedDataAsync) -{ - // Run code that uses `document.setSelectedDataAsync`. -} -``` - ### Specify requirements in a VersionOverrides element The [VersionOverrides](/javascript/api/manifest/versionoverrides) element was added to the manifest schema primarily, but not exclusively, to support features that must be available immediately after an add-in is installed, such as add-in commands (custom ribbon buttons and menus). Office must know about these features when it parses the add-in manifest. @@ -240,7 +180,7 @@ The following is an example. ``` > [!WARNING] -> Use great care before including a **\** element in a **\**, because on platform and version combinations that don't support the requirement, *none* of the add-in commands will be installed, *even those that invoke functionality that doesn't need the requirement*. Consider, for example, an add-in that has two custom ribbon buttons. One of them calls Office JavaScript APIs that are available in requirement set **ExcelApi 1.4** (and later). The other calls APIs that are only available in **ExcelApi 1.9** (and later). If you put a requirement for **ExcelApi 1.9** in the **\**, then when 1.9 is not supported *neither* button will appear on the ribbon. A better strategy in this scenario would be to use the technique described in [Runtime checks for method and requirement set support](#runtime-checks-for-method-and-requirement-set-support). The code invoked by the second button first uses `isSetSupported` to check for support of **ExcelApi 1.9**. If it isn't supported, the code gives the user a message saying that this feature of the add-in is not available on their version of Office. +> If your add-in includes [add-in commands](../design/add-in-commands.md), use great care before including a **\** element in a **\**, because on platform and version combinations that don't support the requirement, *none* of the add-in commands will be installed, *even those that invoke functionality that doesn't need the requirement*. Consider, for example, an add-in that has two custom ribbon buttons. One of them calls Office JavaScript APIs that are available in requirement set **ExcelApi 1.4** (and later). The other calls APIs that are only available in **ExcelApi 1.9** (and later). If you put a requirement for **ExcelApi 1.9** in the **\**, then when 1.9 is not supported *neither* button will appear on the ribbon. A better strategy in this scenario would be to use the technique described in [Check for API availability at runtime](specify-api-requirements-runtime.md). The code invoked by the second button first uses `isSetSupported` to check for support of **ExcelApi 1.9**. If it isn't supported, the code gives the user a message saying that this feature of the add-in is not available on their version of Office. > [!TIP] > There's no point to repeating a **Requirement** element in a **\** that already appears in the base manifest. If the requirement is specified in the base manifest, then the add-in can't install where the requirement isn't supported so Office doesn't even parse the **\** element. diff --git a/docs/toc.yml b/docs/toc.yml index 7ce11495e2..5417ace206 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -96,7 +96,13 @@ items: - name: Reference Office.js href: develop/referencing-the-javascript-api-for-office-library-from-its-cdn.md - name: Specify Office applications and API requirements - href: develop/specify-office-hosts-and-api-requirements.md + items: + - name: Specify Office applications and API requirements with the unified manifest + href: develop/specify-office-hosts-and-api-requirements-unified.md + - name: Specify Office applications and API requirements with the add-in only manifest + href: develop/specify-office-hosts-and-api-requirements.md + - name: Check for API availability at runtime + href: develop/specify-api-requirements-runtime.md - name: Load sequence of an Office Add-in href: develop/loading-the-dom-and-runtime-environment.md - name: Initialize your add-in From 57eea9b5dd2a462bd2808e10f5581eb3d767f49b Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Thu, 3 Oct 2024 16:07:16 -0700 Subject: [PATCH 2/6] link fixes --- docs/design/contextual-tabs.md | 2 +- docs/develop/dialog-api-in-office-add-ins.md | 2 +- docs/develop/specify-api-requirements-runtime.md | 4 ++-- .../specify-office-hosts-and-api-requirements-unified.md | 8 ++++---- docs/develop/specify-office-hosts-and-api-requirements.md | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/design/contextual-tabs.md b/docs/design/contextual-tabs.md index 305097c4c8..6e50030861 100644 --- a/docs/design/contextual-tabs.md +++ b/docs/design/contextual-tabs.md @@ -27,7 +27,7 @@ Additionally, custom contextual tabs only work on platforms that support the fol - [SharedRuntime 1.1](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets) > [!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 [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, 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). +> 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 diff --git a/docs/develop/dialog-api-in-office-add-ins.md b/docs/develop/dialog-api-in-office-add-ins.md index 0ecf31fcac..1423f27186 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 **\** 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 **\** 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 [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 diff --git a/docs/develop/specify-api-requirements-runtime.md b/docs/develop/specify-api-requirements-runtime.md index 7153954694..896e5f3622 100644 --- a/docs/develop/specify-api-requirements-runtime.md +++ b/docs/develop/specify-api-requirements-runtime.md @@ -2,7 +2,7 @@ title: Check for API availability at runtime description: Learn how to verify at runtime that the Office application supports your add-ins API calls. ms.topic: best-practice -ms.date: 11/04/2024 +ms.date: 10/30/2024 ms.localizationpriority: medium --- @@ -60,7 +60,7 @@ else ``` > [!NOTE] -> The `isSetSupported` method and the requirement sets for these applications are available in the latest Office.js file on the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions if you are using an old version of the library in which `isSetSupported` is undefined. For more information, see [Use the latest Office JavaScript API library](#use-the-latest-office-javascript-api-library). +> The `isSetSupported` method and the requirement sets for these applications are available in the latest Office.js file on the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions if you are using an old version of the library in which `isSetSupported` is undefined. For more information, see [Use the latest Office JavaScript API library](specify-office-hosts-and-api-requirements-unified.md#use-the-latest-office-javascript-api-library). ## Check for setless API support diff --git a/docs/develop/specify-office-hosts-and-api-requirements-unified.md b/docs/develop/specify-office-hosts-and-api-requirements-unified.md index db684eac37..0df7b9616b 100644 --- a/docs/develop/specify-office-hosts-and-api-requirements-unified.md +++ b/docs/develop/specify-office-hosts-and-api-requirements-unified.md @@ -2,7 +2,7 @@ title: Specify Office hosts and API requirements with the unified manifest description: Learn how to specify in the unified manifest the Office applications and API requirements for your add-in to work as expected. ms.topic: best-practice -ms.date: 11/04/2024 +ms.date: 10/30/2024 ms.localizationpriority: medium --- @@ -123,7 +123,7 @@ The following code example shows how to configure an add-in that is installable ``` > [!TIP] -> For more information and another example of using the "extensions.requirements" property, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- extensions.requirements](/develop/requirements-property-unified-manifest.md#extensionsrequirements). +> For more information and another example of using the "extensions.requirements" property, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- extensions.requirements](requirements-property-unified-manifest.md#extensionsrequirements). ### Specify the form factors on which your add-in can be installed @@ -157,10 +157,10 @@ If your add-in uses a specific extensibility feature for some of its functionali You implement this design differently depending on how the extensibility feature is implemented: - For features implemented entirely with JavaScript, see [Check for API availability at runtime](specify-api-requirements-runtime.md). -- For features that require you to configure the manifest, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- Filter features](/develop/requirements-property-unified-manifest.md#filter-features). +- For features that require you to configure the manifest, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- Filter features](requirements-property-unified-manifest.md#filter-features). ## See also - [Office Add-ins manifest](add-in-manifests.md) - [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets) -- [Specify Office Add-in requirements in the unified manifest for Microsoft 365](/develop/requirements-property-unified-manifest.md). +- [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md). diff --git a/docs/develop/specify-office-hosts-and-api-requirements.md b/docs/develop/specify-office-hosts-and-api-requirements.md index 4f6c419ee8..ce0279a14c 100644 --- a/docs/develop/specify-office-hosts-and-api-requirements.md +++ b/docs/develop/specify-office-hosts-and-api-requirements.md @@ -2,7 +2,7 @@ title: Specify Office hosts and API requirements with the add-in only manifest description: Learn how to specify Office applications and API requirements for your add-in to work as expected. ms.topic: best-practice -ms.date: 11/04/2024 +ms.date: 10/30/2024 ms.localizationpriority: medium --- From 68d688cc80fa400a70761acd375f1fdd652d1575 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Fri, 4 Oct 2024 17:07:26 -0700 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Sam Ramon <15154970+samantharamon@users.noreply.github.com> --- docs/develop/dialog-api-in-office-add-ins.md | 2 +- .../specify-api-requirements-runtime.md | 29 +++++++++---------- ...fice-hosts-and-api-requirements-unified.md | 16 +++++----- ...ecify-office-hosts-and-api-requirements.md | 8 ++--- 4 files changed, 26 insertions(+), 29 deletions(-) diff --git a/docs/develop/dialog-api-in-office-add-ins.md b/docs/develop/dialog-api-in-office-add-ins.md index 1423f27186..d7292a71cb 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 **\** 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 [Check for API availability at runtime](specify-api-requirements-runtime.md). 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 **\** section of an 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 diff --git a/docs/develop/specify-api-requirements-runtime.md b/docs/develop/specify-api-requirements-runtime.md index 896e5f3622..b55a4e2359 100644 --- a/docs/develop/specify-api-requirements-runtime.md +++ b/docs/develop/specify-api-requirements-runtime.md @@ -1,6 +1,6 @@ --- title: Check for API availability at runtime -description: Learn how to verify at runtime that the Office application supports your add-ins API calls. +description: Learn how to verify at runtime that the Office application supports your add-in's API calls. ms.topic: best-practice ms.date: 10/30/2024 ms.localizationpriority: medium @@ -8,9 +8,9 @@ ms.localizationpriority: medium # Check for API availability at runtime -If your add-in uses a specific extensibility feature for some of its functionality but has other useful functionality that doesn't require the extensibility feature, you should design the add-in so that it's installable on platform and Office version combinations that don't support the extensibility feature. It can provide a valuable, albeit diminished, experience on those combinations. +If your add-in uses a specific extensibility feature for some of its functionality, but has other useful functionality that doesn't require the extensibility feature, you should design the add-in so that it's installable on platform and Office version combinations that don't support the extensibility feature. It can provide a valuable, albeit diminished, experience on those combinations. -When the difference in the two experiences is consists entirely of differences in the Office JavaScript Library APIs that are called, and not in any features that are configured in the manifest, then you test at runtime to discover whether the user's Office supports an [API requirement set](office-versions-and-requirement-sets.md). You can also [test at runtime whether APIs that are not in a set are supported](#check-for-setless-api-support). +When the difference in the two experiences consists entirely of differences in the Office JavaScript Library APIs that are called, and not in any features that are configured in the manifest, then you test at runtime to discover whether the user's Office client supports an [API requirement set](office-versions-and-requirement-sets.md). You can also [test at runtime whether APIs that aren't in a set are supported](#check-for-setless-api-support). > [!NOTE] > To provide alternate experiences with features that require manifest configuration, follow the guidance in [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md) or [Specify Office applications and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md). @@ -20,23 +20,24 @@ When the difference in the two experiences is consists entirely of differences i The [isSetSupported](/javascript/api/office/office.requirementsetsupport#office-office-requirementsetsupport-issetsupported-member(1)) method is used to check for requirement set support. Pass the requirement set's name and the minimum version as parameters. If the requirement set is supported, `isSetSupported` returns `true`. The following code shows an example. ```js -if (Office.context.requirements.isSetSupported("WordApi", "1.2")) -{ +if (Office.context.requirements.isSetSupported("WordApi", "1.2")) { // Code that uses API members from the WordApi 1.2 requirement set. } else { - // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2). + // Provide diminished experience here. + // For example, run alternate code when the user's Word is + // volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2). } ``` About this code, note: - The first parameter is required. It's a string that represents the name of the requirement set. For more information about available requirement sets, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). -- The second parameter is optional. It's a string that specifies the minimum requirement set version that the Office application must support in order for the code within the `if` statement to run (e.g., "1.9"). If not used, version "1.1" is assumed. +- The second parameter is optional. It's a string that specifies the minimum requirement set version that the Office application must support in order for the code within the `if` statement to run (for example, "1.9"). If not used, version "1.1" is assumed. > [!WARNING] -> When calling the `isSetSupported` method, the value of the second parameter (if specified) should be a string not a number. The JavaScript parser cannot differentiate between numeric values such as 1.1 and 1.10, whereas it can for string values such as "1.1" and "1.10". +> When calling the `isSetSupported` method, the value of the second parameter (if specified) should be a string, not a number. The JavaScript parser can't differentiate between numeric values such as 1.1 and 1.10, whereas it can for string values such as "1.1" and "1.10". -The following table shows the requirement set names for the application specific API models. +The following table shows the requirement set names for the application-specific API models. |Office application|RequirementSetName| |---|---| @@ -49,12 +50,9 @@ The following table shows the requirement set names for the application specific The following is an example of using the method with one of the Common API model requirement sets. ```js -if (Office.context.requirements.isSetSupported('CustomXmlParts')) -{ +if (Office.context.requirements.isSetSupported('CustomXmlParts')) { // Run code that uses API members from the CustomXmlParts requirement set. -} -else -{ +} else { // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set. } ``` @@ -72,8 +70,7 @@ When your add-in depends on a method that isn't part of a requirement set, calle The following code example checks whether the Office application supports `document.setSelectedDataAsync`. ```js -if (Office.context.document.setSelectedDataAsync) -{ +if (Office.context.document.setSelectedDataAsync) { // Run code that uses `document.setSelectedDataAsync`. } ``` diff --git a/docs/develop/specify-office-hosts-and-api-requirements-unified.md b/docs/develop/specify-office-hosts-and-api-requirements-unified.md index 0df7b9616b..8112e7aa4a 100644 --- a/docs/develop/specify-office-hosts-and-api-requirements-unified.md +++ b/docs/develop/specify-office-hosts-and-api-requirements-unified.md @@ -54,9 +54,9 @@ To specify the Office applications on which your add-in can be installed, use th | workbook | Excel on the web, Windows, Mac, iPad | Task pane, Content | > [!NOTE] -> Content add-ins have an "extensions.contentRuntimes" property. They cannot have an "extensions.runtimes" property so they cannot be combined with a Task pane or Mail add-in. For more information about Content add-ins, see [Content Office Add-ins](../design/content-add-ins.md). +> Content add-ins have an "extensions.contentRuntimes" property. They can't have an "extensions.runtimes" property so they can't be combined with a Task pane or Mail add-in. For more information about Content add-ins, see [Content Office Add-ins](../design/content-add-ins.md). -For example, the following JSON specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but cannot be installed on any other Office application. +For example, the following JSON specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but can't be installed on any other Office application. ```json "extensions": [ @@ -77,7 +77,7 @@ For example, the following JSON specifies that the add-in can install on any rel You can't explicitly specify the Office versions and builds or the platforms on which your add-in should be installable, and you wouldn't want to because you would have to revise your manifest whenever support for the add-in features that your add-in uses is extended to a new version or platform. Instead, specify in the manifest the APIs that your add-in needs. Office prevents the add-in from being installed on combinations of Office version and platform that don't support the APIs and ensures that the add-in won't appear in **My Add-ins**. > [!IMPORTANT] -> Only use the "requirements" property that is a direct child of "extensions" to specify the API members that your add-in must have to be of any significant value at all. If your add-in uses an API for some features but has other useful features that don't require the API, you should design the add-in so that it's installable on platform and Office version combinations that don't support the API but provides a diminished experience on those combinations. For this purpose, use "requirements" properties that aren't direct children of "extensions". For more information, see [Design for alternate experiences](#design-for-alternate-experiences). +> Only use the "requirements" property that is a direct child of "extensions" to specify the API members that your add-in must have to be of any significant value at all. If your add-in uses an API for some features, but has other useful features that don't require the API, you should design the add-in so that it's installable on platform and Office version combinations that don't support the API but provides a diminished experience on those combinations. For this purpose, use "requirements" properties that aren't direct children of "extensions". For more information, see [Design for alternate experiences](#design-for-alternate-experiences). ### Requirement sets @@ -95,7 +95,7 @@ Requirement set support varies by Office application, the version of the Office Use the "requirements.capabilities" property to specify the minimum requirement sets that must be supported by the Office application to install your add-in. If the Office application or platform doesn't support the requirement sets or API members specified in the "requirements.capabilities" property, the add-in won't run in that application or platform, and won't display in **My Add-ins**. > [!TIP] -> All APIs in the application specific models are in requirement sets, but some of those in the Common API model aren't. If your add-in requires an API that isn't in any requirement set, you can implement a runtime check for the availability of the API and display a message to the add-in's users if it isn't supported. For more information, see [Check for API availability at runtime](specify-api-requirements-runtime.md). +> All APIs in the application-specific models are in requirement sets, but some of those in the Common API model aren't. If your add-in requires an API that isn't in any requirement set, you can implement a runtime check for the availability of the API and display a message to the add-in's users if it isn't supported. For more information, see [Check for API availability at runtime](specify-api-requirements-runtime.md). The following code example shows how to configure an add-in that is installable in all Office application and platform combinations that support the following: @@ -123,11 +123,11 @@ The following code example shows how to configure an add-in that is installable ``` > [!TIP] -> For more information and another example of using the "extensions.requirements" property, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- extensions.requirements](requirements-property-unified-manifest.md#extensionsrequirements). +> For more information and another example of using the "extensions.requirements" property, see the "extensions.requirements" section in [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md#extensionsrequirements). ### Specify the form factors on which your add-in can be installed -For an Outlook add-in is installable on desktop, you can also specify whether the add-in should be installable on desktop (includes tablets) or mobile form factors. Use the "extensions.requirements.formFactors" property. The following example show how to make the Outlook add-in installable on both form factors. +For an Outlook add-in, you can specify whether the add-in should be installable on desktop (includes tablets) or mobile form factors. To configure this, use the "extensions.requirements.formFactors" property. The following example show how to make the Outlook add-in installable on both form factors. ```json "extensions": [ @@ -157,10 +157,10 @@ If your add-in uses a specific extensibility feature for some of its functionali You implement this design differently depending on how the extensibility feature is implemented: - For features implemented entirely with JavaScript, see [Check for API availability at runtime](specify-api-requirements-runtime.md). -- For features that require you to configure the manifest, see [Specify Office Add-in requirements in the unified manifest for Microsoft 365 -- Filter features](requirements-property-unified-manifest.md#filter-features). +- For features that require you to configure the manifest, see the "Filter features" section of [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md#filter-features). ## See also - [Office Add-ins manifest](add-in-manifests.md) - [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets) -- [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md). +- [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md) diff --git a/docs/develop/specify-office-hosts-and-api-requirements.md b/docs/develop/specify-office-hosts-and-api-requirements.md index ce0279a14c..6c287dd97e 100644 --- a/docs/develop/specify-office-hosts-and-api-requirements.md +++ b/docs/develop/specify-office-hosts-and-api-requirements.md @@ -13,7 +13,7 @@ ms.localizationpriority: medium Your Office Add-in might depend on a specific Office application (also called an Office host) or on specific members of the Office JavaScript Library (office.js). For example, your add-in might: -- Run in a single Office application (e.g., Word or Excel), or several applications. +- Run in a single Office application (for example, Word or Excel), or several applications. - Make use of Office JavaScript APIs that are only available in some versions of Office. For example, the volume-licensed perpetual version of Excel 2016 doesn't support all Excel-related APIs in the Office JavaScript library. In these situations, you need to ensure that your add-in is never installed on Office applications or Office versions in which it cannot run. @@ -45,7 +45,7 @@ By default, an add-in is installable in all Office applications supported by the To ensure that your add-in is installable in only a subset of Office applications, use the [Hosts](/javascript/api/manifest/hosts) and [Host](/javascript/api/manifest/host) elements in the add-in only manifest. -For example, the following **\** and **\** declaration specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but cannot be installed on any other Office application. +For example, the following **\** and **\** declaration specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but can't be installed on any other Office application. ```xml @@ -180,10 +180,10 @@ The following is an example. ``` > [!WARNING] -> If your add-in includes [add-in commands](../design/add-in-commands.md), use great care before including a **\** element in a **\**, because on platform and version combinations that don't support the requirement, *none* of the add-in commands will be installed, *even those that invoke functionality that doesn't need the requirement*. Consider, for example, an add-in that has two custom ribbon buttons. One of them calls Office JavaScript APIs that are available in requirement set **ExcelApi 1.4** (and later). The other calls APIs that are only available in **ExcelApi 1.9** (and later). If you put a requirement for **ExcelApi 1.9** in the **\**, then when 1.9 is not supported *neither* button will appear on the ribbon. A better strategy in this scenario would be to use the technique described in [Check for API availability at runtime](specify-api-requirements-runtime.md). The code invoked by the second button first uses `isSetSupported` to check for support of **ExcelApi 1.9**. If it isn't supported, the code gives the user a message saying that this feature of the add-in is not available on their version of Office. +> If your add-in includes [add-in commands](../design/add-in-commands.md), use great care before including a **\** element in a **\**. On platform and version combinations that don't support the requirement, *none* of the add-in commands will be installed, *even those that invoke functionality that doesn't need the requirement*. Consider, for example, an add-in that has two custom ribbon buttons. One of them calls Office JavaScript APIs that are available in requirement set **ExcelApi 1.4** (and later). The other calls APIs that are only available in **ExcelApi 1.9** (and later). If you put a requirement for **ExcelApi 1.9** in the **\**, then when 1.9 isn't supported, *neither* button will appear on the ribbon. A better strategy in this scenario would be to use the technique described in [Check for API availability at runtime](specify-api-requirements-runtime.md). The code invoked by the second button first uses `isSetSupported` to check for support of **ExcelApi 1.9**. If it isn't supported, the code gives the user a message saying that this feature of the add-in isn't available on their version of Office. > [!TIP] -> There's no point to repeating a **Requirement** element in a **\** that already appears in the base manifest. If the requirement is specified in the base manifest, then the add-in can't install where the requirement isn't supported so Office doesn't even parse the **\** element. +> There's no point to repeating a **\** element in a **\** that already appears in the base manifest. If the requirement is specified in the base manifest, then the add-in can't install where the requirement isn't supported so Office doesn't even parse the **\** element. ## See also From 4b2bad35e27389486535d211c6fefebf538d40d8 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Fri, 4 Oct 2024 17:09:28 -0700 Subject: [PATCH 4/6] Update docs/develop/specify-office-hosts-and-api-requirements-unified.md --- .../specify-office-hosts-and-api-requirements-unified.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/develop/specify-office-hosts-and-api-requirements-unified.md b/docs/develop/specify-office-hosts-and-api-requirements-unified.md index 8112e7aa4a..7cdcef036f 100644 --- a/docs/develop/specify-office-hosts-and-api-requirements-unified.md +++ b/docs/develop/specify-office-hosts-and-api-requirements-unified.md @@ -49,7 +49,7 @@ To specify the Office applications on which your add-in can be installed, use th | Name | Office client applications | Available add-in types | |:--------------|:-----------------------------------------------|:-----------------------| | document | Word on the web, Windows, Mac, iPad | Task pane | -| mail | Outlook on the web, Windows ([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) and classic), Mac, Android, iOS | Mail | +| mail | Outlook on the web, Windows ([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) and classic), Android, iOS | Mail | | presentation | PowerPoint on the web, Windows, Mac, iPad | Task pane, Content | | workbook | Excel on the web, Windows, Mac, iPad | Task pane, Content | From 27bbc3b79f7b6b5bf84ea6fadca1f03d62899278 Mon Sep 17 00:00:00 2001 From: Ricky Kirkham Date: Fri, 4 Oct 2024 17:15:00 -0700 Subject: [PATCH 5/6] add glossary entry --- docs/resources/resources-glossary.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/resources/resources-glossary.md b/docs/resources/resources-glossary.md index e7425d5809..511ec20cce 100644 --- a/docs/resources/resources-glossary.md +++ b/docs/resources/resources-glossary.md @@ -1,7 +1,7 @@ --- title: Office Add-ins glossary of terms description: A glossary of terms commonly used throughout the Office Add-ins documentation. -ms.date: 10/01/2024 +ms.date: 10/05/2024 ms.topic: glossary ms.localizationpriority: medium --- @@ -146,6 +146,12 @@ A **runtime** is the host environment (including a JavaScript engine and usually See also: [custom functions runtime](#custom-functions-runtime), [shared runtime](#shared-runtime), [webview](#webview). +## setless API + +An API in the Office JavaScript Library that is not included in any requirement set. + +See also [requirement set](#requirement-set). + ## shared runtime A **shared runtime**, enables code in your task pane, function commands, and custom functions, to run in the same runtime and continue running even when the task pane is closed. Code in dialogs generally runs in a separate runtime even when the add-in is configured to use a shared runtime. See [shared runtime](../testing/runtimes.md#shared-runtime) and [Tips for using the shared runtime in your Office Add-in](https://devblogs.microsoft.com/microsoft365dev/tips-for-using-the-shared-javascript-runtime-in-your-office-add-in%e2%80%af/) to learn more. From 1e61ab0727554b5b14e046d690a0c6c617c81d94 Mon Sep 17 00:00:00 2001 From: Rick Kirkham Date: Thu, 10 Oct 2024 12:35:16 -0700 Subject: [PATCH 6/6] Update docs/toc.yml --- docs/toc.yml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/toc.yml b/docs/toc.yml index 5417ace206..7ce11495e2 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -96,13 +96,7 @@ items: - name: Reference Office.js href: develop/referencing-the-javascript-api-for-office-library-from-its-cdn.md - name: Specify Office applications and API requirements - items: - - name: Specify Office applications and API requirements with the unified manifest - href: develop/specify-office-hosts-and-api-requirements-unified.md - - name: Specify Office applications and API requirements with the add-in only manifest - href: develop/specify-office-hosts-and-api-requirements.md - - name: Check for API availability at runtime - href: develop/specify-api-requirements-runtime.md + href: develop/specify-office-hosts-and-api-requirements.md - name: Load sequence of an Office Add-in href: develop/loading-the-dom-and-runtime-environment.md - name: Initialize your add-in