Activate your Outlook add-in without the Reading Pane enabled or a message selected
With a simple manifest configuration, you can create Outlook add-ins for the Message Read surface that activate a task pane without the Reading Pane enabled or a message first selected from the mailbox. This feature is called "no item context". Follow the walkthrough to learn more and unlock additional capabilities for your add-in. For example, you can enable your users to access content from different data sources, such as OneDrive or a customer relationship management (CRM) system, directly from their Outlook client.
Note
Support for this feature was introduced in requirement set 1.13. See clients and platforms that support this requirement set.
Although Outlook on the web and new Outlook on Windows support requirement set 1.13, an add-in won't activate if the Reading Pane is hidden or a message isn't selected. For more information, see Feature support in Outlook on the web and new Outlook on Windows.
Set up your environment
Complete the Outlook quick start in which you create an Outlook add-in with the Yeoman generator for Office Add-ins.
To turn on this feature in a preexisting add-in project, see Configure the manifest.
Configure the manifest
The steps to configure the manifest vary depending on which type of manifest your add-in uses.
In your preferred code editor, open the Outlook quick start project that you created.
Open the manifest.json file located at the root of the project.
In the first object in the "extensions.runtimes" array, do the following:
- Change the "requirements.capabilities.minVersion" to "1.13".
- Add a "supportsNoItemContext" property to the object in the "actions" array and set its value to
true
. - Add a "multiselect" property to the same object and set it to
true
. - Change the "pinnable" property in the same object to
true
.
When you are done, it should look like the following.
"runtimes": [ { "requirements": { "capabilities": [ { "name": "Mailbox", "minVersion": "1.13" } ] }, "id": "TaskPaneRuntime", "type": "general", "code": { "page": "https://localhost:3000/taskpane.html" }, "lifetime": "short", "actions": [ { "id": "TaskPaneRuntimeShow", "type": "openPage", "view": "dashboard", "pinnable": true, "supportsNoItemContext": true, "multiselect": true } ] } ]
Delete the second object in the "extensions.runtimes" array, whose "id" is "CommandsRuntime".
The "extensions.ribbons.tabs.groups.controls" array has two objects. Delete the second one, whose "id" is "ActionButton".
Configure the task pane
In your project, navigate to the taskpane folder, then open taskpane.html.
Replace the entire <body> element with the following markup.
<body class="ms-font-m ms-welcome ms-Fabric"> <header class="ms-welcome__header ms-bgColor-neutralLighter"> <img width="90" height="90" src="../../assets/logo-filled.png" alt="logo" title="Add-in logo" /> <h1 class="ms-font-su">Activate your add-in without enabling the Reading Pane or selecting a message</h1> </header> <section id="sideload-msg" class="ms-welcome__main"> <h2 class="ms-font-xl">Please <a target="_blank" href="https://learn.microsoft.com/office/dev/add-ins/testing/test-debug-office-add-ins#sideload-an-office-add-in-for-testing">sideload</a> your add-in to see app body.</h2> </section> <main id="app-body" class="ms-welcome__main" style="display: none;"> <ul class="ms-List ms-welcome__features"> <li class="ms-ListItem"> <i class="ms-Icon ms-Icon--CheckList ms-font-xl"></i> <span class="ms-font-m">Item multi-select is automatically enabled when the <b>SupportsNoItemContext</b> manifest element is set to <code>true</code>. You can test this by selecting multiple messages in Outlook, then choosing <b>Show Taskpane</b> from the ribbon.</span> </li> <li class="ms-ListItem"> <i class="ms-Icon ms-Icon--Pin ms-font-xl"></i> <span class="ms-font-m">Support to pin the task pane is also automatically enabled. You can test this by selecting the <b>pin</b> icon from the top right corner of the task pane.</span> </li> <li class="ms-ListItem"> <i class="ms-Icon ms-Icon--DockRight ms-font-xl"></i> <span class="ms-font-m">This feature can only be implemented with a task pane.</span> </li> <li class="ms-ListItem"> <i class="ms-Icon ms-Icon--Design ms-font-xl"></i> <span class="ms-font-m">Implement your scenario using this feature today! For example, enable your users to access content from different data sources, such as OneDrive or your customer relationship management (CRM) system, without first selecting a message.</span> </li> </ul> </main> </body>
Save your changes.
Update the task pane JavaScript file
From the taskpane folder, open taskpane.js.
Navigate to the
Office.onReady
function and replace its contents with the following code.if (info.host === Office.HostType.Outlook) { document.getElementById("sideload-msg").style.display = "none"; document.getElementById("app-body").style.display = "flex"; }
Save your changes.
Try it out
From a terminal, run the following code in the root directory of your project. This starts the local web server and sideloads your add-in.
npm start
Tip
If your add-in doesn't automatically sideload, follow the instructions in Sideload Outlook add-ins for testing to manually sideload it in Outlook.
Navigate to your inbox and do one of the following:
- Turn off your Reading Pane. For guidance, see the "Turn on, turn off, or move the Reading Pane" section of Use and configure the Reading Pane to preview messages.
- Deselect a message, if applicable. To deselect a message, hold the Ctrl key and select the message.
Select Show Taskpane from the ribbon.
Explore and test the suggestions listed in the task pane.
Support for the item multi-select and pinnable task pane features
Enabling support for no item context in the manifest automatically enables support for item multi-select and pinnable task pane features, even if these features aren't explicitly configured in the manifest.
Feature support in Outlook on the web and new Outlook on Windows
In Outlook on the web and new Outlook on Windows, add-ins that implement no item context don't activate when the Reading Pane is hidden or when a message isn't selected. This is because add-in commands in Outlook on the web don't appear on the ribbon. To activate an add-in from the Message Read surface, you must first select a message, then select the add-in command from the message action bar.
Since enabling no item context automatically enables the item multi-select feature, you'll be able to activate your add-in in Outlook on the web and new Outlook on Windows on multiple mail items.
See also
Office Add-ins