Skip to content

Commit

Permalink
Merge pull request #4334 from OfficeDev/unified-manifest-support-outl…
Browse files Browse the repository at this point in the history 
…ook-mobile

[Outlook] (manifest) mobile support in unified manifest
  • Loading branch information
@Rick-Kirkham
Rick-Kirkham committed May 3, 2024
2 parents f722e54 + a9a2b5c commit 9d2a1af
Show file tree
Hide file tree
Showing 4 changed files with 423 additions and 204 deletions.
124 changes: 120 additions & 4 deletions docs/outlook/add-mobile-support.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Add support for add-in commands in Outlook on mobile devices
description: Learn how to add support for Outlook on mobile devices including how to update the add-in manifest and change your code for mobile scenarios, if necessary.
ms.date: 02/29/2024
ms.date: 04/12/2024
ms.localizationpriority: medium
---

Expand All @@ -11,9 +11,123 @@ Using add-in commands in Outlook on mobile devices allows your users to access t

## Update the manifest

[!INCLUDE [Unified manifest for Microsoft 365 not supported on mobile devices](../includes/no-mobile-with-json-note.md)]

The first step to enabling add-in commands in Outlook mobile is to define them in the add-in manifest. The [VersionOverrides](/javascript/api/manifest/versionoverrides) v1.1 schema defines a new form factor for mobile, [MobileFormFactor](/javascript/api/manifest/mobileformfactor).
The first step to enabling add-in commands in Outlook mobile is to define them in the add-in manifest.

# [Unified manifest for Microsoft 365](#tab/jsonmanifest)

1. In the "extensions.ribbons.requirements.formFactors" array, add "mobile" as an item. When you are finished, the array should look like the following.

```json
"formFactors": [
"mobile",
<!-- Typically there will be other form factors listed. -->
]
```

1. If your add-in uses Appointment Attendee mode, such as an add-in that integrates a provider of a note-taking or customer relationship management (CRM) application, add "logEventMeetingDetailsAttendee" to the "extensions.ribbons.contexts" array. The following is an example.

```json
"contexts": [
"meetingDetailsAttendee",
"logEventMeetingDetailsAttendee"
],
```

1. If your add-in uses an integrated online meeting provider, add "onlineMeetingDetailsOrganizer" to the "extensions.ribbons.contexts" array. The following is an example.

```json
"contexts": [
"meetingDetailsOrganizer",
"onlineMeetingDetailsOrganizer"
],
```

1. In the "extensions.ribbons.tabs" array, find the tab with the "builtInTabId" of "TabDefault". Add a child "customMobileRibbonGroups" array to it (as a peer of the existing "groups" property). Inside this array, create an object and do the following:

- Set appropriate "id" and "label" values.
- Create an object in the "controls" array to represent a button and configure it as follows.
- Set appropriate "id" and "label" values.
- Set "buttonType" to "MobileButton".
- Assign a function to the "actionId" property. This should match the "id" of the object in the "extensions.runtimes.actions" array.
- Be sure you have all nine required icons.

The following is an example.

```json
"tabs": [
{
"builtInTabId": "TabDefault",
"groups": [
<-- non-mobile group objects omitted -->
],
"customMobileRibbonGroups": [
{
"id": "mobileApptComposeGroup",
"label": "Contoso Meeting",
"controls": [
{
"id": "mobileInsertMeetingButton",
"label": "Add Meeting",
"buttonType": "MobileButton",
"actionId": "insertContosoMeeting",
"icons": [
{
"scale": 1,
"size": 25,
"url": "https://contoso.com/assets/icon-25.png"
},
{
"scale": 1,
"size": 32,
"url": "https://contoso.com/assets/icon-32.png"
},
{
"scale": 1,
"size": 48,
"url": "https://contoso.com/assets/icon-48.png"
},
{
"scale": 2,
"size": 25,
"url": "https://contoso.com/assets/icon-25.png"
},
{
"scale": 2,
"size": 32,
"url": "https://contoso.com/assets/icon-32.png"
},
{
"scale": 2,
"size": 48,
"url": "https://contoso.com/assets/icon-48.png"
},
{
"scale": 3,
"size": 25,
"url": "https://contoso.com/assets/icon-25.png"
},
{
"scale": 3,
"size": 32,
"url": "https://contoso.com/assets/icon-32.png"
},
{
"scale": 3,
"size": 48,
"url": "https://contoso.com/assets/icon-48.png"
}
]
}
]
}
]
}
]
```

# [XML manifest](#tab/xmlmanifest)

The [VersionOverrides](/javascript/api/manifest/versionoverrides) v1.1 schema defines a new form factor for mobile, [MobileFormFactor](/javascript/api/manifest/mobileformfactor).

This element contains all of the information for loading the add-in in mobile clients. This enables you to define completely different UI elements and JavaScript files for the mobile experience.

Expand Down Expand Up @@ -61,6 +175,8 @@ This is very similar to the elements that appear in a [DesktopFormFactor](/javas
- The [Supertip](/javascript/api/manifest/supertip) element isn't used.
- The required icon sizes are different. Mobile add-ins minimally must support 25x25, 32x32 and 48x48 pixel icons. For more information, see [Additional requirements for mobile form factors](/javascript/api/manifest/icon#additional-requirements-for-mobile-form-factors).

---

## Code considerations

Designing an add-in for mobile introduces some additional considerations.
Expand Down
71 changes: 66 additions & 5 deletions docs/outlook/mobile-event-based.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Implement event-based activation in Outlook mobile add-ins
description: Learn how to develop an Outlook mobile add-in that implements event-based activation.
ms.date: 02/29/2024
ms.date: 04/12/2024
ms.topic: how-to
ms.localizationpriority: medium
---
Expand All @@ -23,12 +23,71 @@ The add-in you develop in this walkthrough is supported in Outlook on Android an

## Set up your environment

Complete the [Outlook quick start](../quickstarts/outlook-quickstart.md?tabs=yeomangenerator), which creates an add-in project with the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md).
Complete the [Outlook quick start](../quickstarts/outlook-quickstart.md?tabs=yeomangenerator) in which you create an add-in project with the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md).

## Configure the manifest

> [!NOTE]
> The [Unified Microsoft 365 manifest (preview)](../develop/json-manifest-overview.md) isn't currently supported on mobile devices.
The steps for configuring the manifest depend on which type of manifest you selected in the quick start.

# [Unified manifest for Microsoft 365](#tab/jsonmanifest)

1. Configure the "extensions.runtimes" property just as you would for setting up a function command. For details, see [Configure the runtime for the function command](../develop/create-addin-commands-unified-manifest.md#configure-the-runtime-for-the-function-command).

1. In the "extensions.ribbons.contexts" array, add `mailRead` as an item. When you're finished, the array should look like the following.

```json
"contexts": [
"mailRead"
],
```

1. In the "extensions.ribbons.requirements.formFactors" array, add "mobile" as an item. When you're finished, the array should look like the following.

```json
"formFactors": [
"mobile",
<!-- Typically there will be other form factors listed. -->
]
```

1. Add the following "autoRunEvents" array as a property of the object in the "extensions" array.

```json
"autoRunEvents": [

]
```

1. Add an object like the following to the "autoRunEvents" array. Note the following about this code:

- The "events" property maps handlers to events.
- The "events.type" must be one of the types listed at [Supported events](autolaunch.md#supported-events).
- The value of the "events.actionId" is the name of a function that you create in [Implement the event handler](#implement-the-event-handler).
- You can have more than one object in the "events" array.

```json
{
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.10"
}
],
"scopes": [
"mail"
]
},
"events": [
{
"type": "newMessageComposeCreated",
"actionId": "onNewMessageComposeHandler"
},
]
}
```

# [XML manifest](#tab/xmlmanifest)

To enable an event-based add-in on Outlook mobile, you must configure the following elements in the `VersionOverridesV1_1` node of the manifest.

Expand Down Expand Up @@ -140,6 +199,8 @@ To enable an event-based add-in on Outlook mobile, you must configure the follow

1. Save your changes.

---

> [!TIP]
> To learn more about manifests for Outlook add-ins, see [Office Add-ins manifest](../develop/add-in-manifests.md) and [Add support for add-in commands in Outlook on mobile devices](add-mobile-support.md).
Expand Down Expand Up @@ -218,7 +279,7 @@ To enable your add-in to complete tasks when the `OnNewMessageCompose` event occ

## Add a reference to the event-handling JavaScript file

Ensure that the HTML file you specified in the **\<Runtime\>** element of your manifest has a reference to the JavaScript file that contains your event handler.
Ensure that the **./src/commands/commands.html** file has a reference to the JavaScript file that contains your event handler.

1. Navigate to the **./src/commands** folder, then open **commands.html**.
1. Immediately before the closing **head** tag (`</head>`), add a script entry for the JavaScript file that contains the event handler.
Expand Down

0 comments on commit 9d2a1af

Please sign in to comment.