Have your add-in users been asking you for the ability to leave the add-in taskpane open in their mailbox as they switch between messages? At Ignite this year, we announced the addition of a new feature for Outlook add-ins, the Pinnable Taskpane. Today we are excited to announce this feature is now officially available in the subscription version (C2R) of Outlook 2016 for Windows users! The feature is identifiable by a pin icon as shown in the screenshot below and will only be available for taskpanes which have explicitly added support. We’ve provided some getting started instructions in this post.

A screenshot of a pinnable taskpane in Outlook. Note the pin icon in the upper right corner of the taskpane.

Please note the pinnable taskpane functionality defaults to off.  We chose to do this because we wanted the users to remain in control of their Outlook experience.  To ensure users leverage the “pinning” functionality we encourage you to show some teaching UI to tell users they can pin the add-in, if they want. Take a look at our design guidelines around First-Run experiences and toast notifications.

There are two main changes that need to be made to add-ins to support the Pinnable Taskpane: updating the manifest and registering for the ItemChanged event.

Updating the manifest

Last year we added a VersionOverrides version 1.0 section to the manifest with the release of add-in commands. As we continued to add new functionality we introduced VersionOverrides version 1.1 which is what you’ll need to add support for the Pinnable Taskpane. Adding the SupportsPinning tag to a ShowTaskPane action of a control indicates that the task pane support pinning. Below is an example of an extension point that supports pinning. Notice the SupportsPinning tag.

<Control xsi:type="Button" id="Contoso.Button0">
  <Label resid="residTaskpaneButton"></Label>
  <Tooltip>
    <Title resid="residTipTitle"></Label>
    <Description resid="residTipDescription"></Label>
  </Tooltip>

  <Icon>
    <bt:Image size="16" resid="functionIcon" />     
    <bt:Image size="32" resid="functionIcon" />
    <bt:Image size="80" resid="functionIcon" />
  </Icon>

  <Action xsi:type="ShowTaskPane">
    <SourceLocation resid="residTaskpaneUrl"/>
    <SupportsPinning>true</SupportsPinning>
  </Action>
</Control>

Registering for the ItemChanged Event

Now that the taskpane’s support has been declared in the manifest, the add-in must register to get an event when a new item is shown in the user’s mailbox. This can be done by leveraging the new Office.context.mailbox.addHandlerAsync API in Office.initialize. This API takes the following parameters: eventType, handler[,options], callback. Be sure to register for the ItemChanged event. Below is an example of how this might look:

Office.context.mailbox.addHandlerAsync(
  Office.EventType.ItemChanged,
  function(eventArgs) {
    // This is the event handler. Do something here.
  },
  function(asyncResult) {
    // This is callback for addHandlerAsync. This will be called ONCE when the event is registered.
  }
);

Interested in learning more about the Pinnable Taskpane? Take a look at the documentation here.