Edit

Share via

Activate your Outlook add-in without the Reading Pane enabled or a message selected

  • Article

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.

  1. In your preferred code editor, open the Outlook quick start project that you created.

  2. Open the manifest.json file located at the root of the project.

  3. In the first object in the "extensions.runtimes" array, do the following:

    1. Change the "requirements.capabilities.minVersion" to "1.13".
    2. Add a "supportsNoItemContext" property to the object in the "actions" array and set its value to true.
    3. Add a "multiselect" property to the same object and set it to true.
    4. Change the "pinnable" property in the same object to true.

    When you are done, it should look like the following.

    JSON 
    "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
            }
        ]
    }
]

  4. Delete the second object in the "extensions.runtimes" array, whose "id" is "CommandsRuntime".

  5. The "extensions.ribbons.tabs.groups.controls" array has two objects. Delete the second one, whose "id" is "ActionButton".

Configure the task pane

  1. In your project, navigate to the taskpane folder, then open taskpane.html.

  2. Replace the entire <body> element with the following markup.

    HTML 
    <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>

  3. Save your changes.

Update the task pane JavaScript file

  1. From the taskpane folder, open taskpane.js.

  2. Navigate to the Office.onReady function and replace its contents with the following code.

    JavaScript 
    if (info.host === Office.HostType.Outlook) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
}

  3. Save your changes.

Try it out

  1. 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.

    command line 
    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.

  2. Navigate to your inbox and do one of the following:

  3. Select Show Taskpane from the ribbon.

  4. Explore and test the suggestions listed in the task pane.

  5. When you want to stop the local web server and uninstall the add-in, follow the applicable instructions:

    • To stop the server, run the following command. If you used npm start, the following command should also uninstall the add-in.

      command line 
      npm stop

    • If you manually sideloaded the add-in, see Remove a sideloaded add-in.

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