Outlook add-ins overview
In a nutshell
Outlook add-ins let you extend the functionality of Outlook on the following platforms:
- Windows desktop app (new and classic versions)
- macOS desktop app
- Outlook web app
- Outlook mobile app
An Outlook add-in consists of two main parts:
- A manifest file that defines the settings and capabilities of the add-in.
- The web app that provides the UI and functionality of add-in components like task panes, content panes, and dialog boxes. Outlook will render your web app in a WebView.
Create an add-in
Install the latest version of Yeoman and the Yeoman generator:
npm install -g yo generator-officeCreate project:
yo officeFollow the subsequent prompts and answer as needed and you should get a folder with some code:
- The ./manifest.json or ./manifest.xml file in the root directory of the project defines the settings and capabilities of the add-in.
- The ./src/taskpane/taskpane.html file contains the HTML markup for the task pane.
- The ./src/taskpane/taskpane.css file contains the CSS that’s applied to content in the task pane.
- The ./src/taskpane/taskpane.js file contains the Office JavaScript API code that facilitates interaction between the task pane and Outlook.
Run:
npm run startSideload the add-in by following the instructions here.
manifest.xml reference
The manifest.xml file defines the settings and capabilities of the add-in. You’ll configure the manifest to specify things such as:
- Metadata that describes the add-in (for example, ID, version, description, display name, default locale).
- Office applications where the add-in will run.
- Permissions that the add-in requires.
- How the add-in integrates with Office, including any custom UI that the add-in creates (for example, a custom tab or custom ribbon buttons).
- Location of images that the add-in uses for branding and command iconography.
- Dimensions of the add-in (for example, dimensions for content add-ins, requested height for Outlook add-ins).
- Rules that specify when the add-in activates in the context of a message or appointment (for Outlook add-ins only).
- Keyboard shortcuts (for Excel only).
- ExtensionPoint: lets you define if you want to add buttons to read message window (
MessageReadCommandSurface) or the compose message window (MessageComposeCommandSurface).
Office JavaScript API library
An Office Add-in can use the Office JavaScript APIs to interact with content in the Office document where the add-in is running.
The Office JavaScript API library can be accessed via the Office JS content delivery network (CDN) at: https://appsforoffice.microsoft.com/lib/1/hosted/office.js. To use Office JavaScript APIs within any of your add-in’s web pages, you must reference the CDN in a <script> tag in the <head> tag of the page.
<head>
...
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>
</head>Requirement sets
You define requirement sets to specify what API requirements your add-in has.
Office Dialog API
You can use the Office dialog API to open dialog boxes in your Office add-in for things like:
- Sign in a user with a resource such as Google, Facebook, or Microsoft identity. For more information, see Authenticate with the Office dialog API.
- Provide more screen space, or even a full screen, for some tasks in your add-in.
- Host a video that would be too small if confined to a task pane.
Open a dialog box from a host page
The Office JavaScript APIs include a Dialog object and two functions in the Office.context.ui namespace.
To open a dialog box, your code, typically a page in a task pane, calls the displayDialogAsync method and passes to it the URL of the resource that you want to open. The page on which this method is called is known as the “host page”. For example, if you call this method in script on index.html in a task pane, then index.html is the host page of the dialog box that the method opens.
Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html');The host page and the resource that opens in the dialog box must have the same full domain. If you attempt to pass displayDialogAsync a subdomain of the add-in’s domain, it won’t work. The full domain, including any subdomain, must match.
Configure dialog box height
By default, the dialog box will occupy 80% of the height and width of the device screen, but you can set different percentages by passing a configuration object to the method, as shown in the following example.
Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', {height: 30, width: 20});Send information from the dialog box to the host page
Code in a dialog box uses the messageParent function to send a string message to the host page. This string can be a word, sentence, XML blob, stringified JSON, or anything else that can be serialized to a string or cast to a string.
initialise your add-in and then use the messageParent function like so:
Office.context.ui.messageParent({ someMessage: 'foo'} );The host message can be configured to receive this message by adding a callback to the original call of Office.context.ui.displayDialogAsync which will assign it as a handler to the DialogMessageReceived event:
Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', {height: 30, width: 20},
function (asyncResult) {
const dialog = asyncResult.value
dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
dialog.close();
processMessage(arg);
})
}
)Here, we’re saying that if the page at https://www.contoso.com/myDialog.html sends a message, then we want to invoke the callback.
Send a message from the host to the dialog
When you call the Office dialog API to open a dialog box, a Dialog object is returned. It should be assigned to a variable that has global scope so that you can reference it from other functions. The following is an example.
This Dialog object has a messageChild method that sends any string, including stringified data, to the dialog box. This raises a DialogParentMessageReceived event in the dialog box. Your code should handle this event, as shown in the next section.
// Send message from host
function someAction() {
const messageToDialog = JSON.stringify({
name: "My Sheet",
position: 2
})
dialog.messageChild(messageToDialog)
}
// Then
Office.onReady(function () {
Office.context.ui.addHandlerAsync(Office.EventType.DialogParentMessageReceived,
onMessageFromParent)
})Notes
- Outlook items can be configured to be made available for when
- Reading a mail item
- Composing a mail item
- Assuming you setup your project with the Yeoman generator, you can validate your manifest file with
npm run validate. - If you want to publish your add-on via AppSource, you’ll need to conform to the Commercial marketplace certification policies.
- Add-ins won’t be activated if the current message item is IRM-protected.