Posted by on Oct 16, 2015 in #Office365Dev | 2 comments

The ribbon is a powerful tool for navigating around the various of features and mechanisms in the Office products. Lately we have introduced a first wave of capabilities when it comes to integrating with the ribbon with your Office add-ins. As for a start, you can create add-in commands for Outook 2016 (for Windows desktop).

We are starting out with Outlook 2016, but as we make progress – your add-in commands will with tiny effort show up in the other flavors of Outlook (i.e. Outlook Online).

outlookaddins

You will create your add-in commands in a way that won’t break your add-ins if they run on a platform where add-in commands aren’t yet supported – so it’s very flexible and you can get going right away. We will take care of the rest for you.

In order to get started – learn how to deploy add-ins to your Outlook 2016 (for Windows desktop) application here: http://simonjager.com/installing-add-ins-in-outlook-2016-and-outlook-online/

Extending the manifest file
Start out by opening your manifest file (*.xml) in code. I created a new one from scratch – which looked like this:

After the DisableEntityHighlighting tag – we need to extend the manifest. We will create a new tag named VersionOverrides (https://msdn.microsoft.com/en-us/library/office/mt267547.aspx) – which is a way for Outlook to detect version specific capabilities in your add-in.

In VersionOverrides – we need to define a new Host, which in this case is a MailHost (Outlook). Finally create a section for DesktopFormFactor – this is where we can extend the different surface areas in the desktop version of Outlook.

Creating and referencing a JavaScript function
Depending on how you’re extending Outlook – you will most likely want some form of logic to run when a user interacts with your add-in commands. We will create a JavaScript file containing the functions to be executed.

In order for Outlook to run a JavaScript function when a user interacts with an add-in command, there are a couple of things you need to do:

  • Add a JavaScript file with the functions to be executed
  • Set the Office.initialize function
  • Add an HTML file (which loads the JavaScript file)
  • Add a reference to the HTML file (and function name) in the manifest file

I added my files (HTML + JavaScript) into a single folder like so:

functionsfile

The HTML file (Functions.html) doesn’t need to contain anything else other than actual references to the JavaScript files that you’re planning on using (i.e. jQuery, Office.JS and your JavaScript file).

My JavaScript file (Functions.js) looks like this, very simple – I hooked up an initialize function for the Office library (so that I can interact with the mail context) and define the function to be executed with the add-in command. Feel free to define all of your add-in command functions in this file if it suits you.

Remember to call event.completed() when your function has finished. This will make sure that Outlook presents a proper notification experience for the user.

Finally we need to reference the HTML file (which loads the JavaScript file) in the manifest file. Simply add a FunctionFile tag in the DesktopFormFactor section.

Instead of creating a file reference right away in the tag – we will reference a resource instead (with the resid attribute), this way we can reuse that piece of data over and over. Start defining your resource after the Hosts tag like I did. Point out the Url to the web server where your add-in (function file) is hosted.

Make sure that the resid in the FunctionFile tag corresponds to a Url resource with the same id.

Let me visualize what we are achieving here:

addincommand

Creating the add-in command
Now get back to the DesktopFormFactor section and create an ExtensionPoint. Right now you can extend five different surface areas; CustomPane, MessageComposeCommandSurface, MessageReadCommandSurface, AppointmentOrganizerCommandSurface and AppointmentAttendeeCommandSurface.

You will create an ExtensionPoint for each area that you want to integrate with, this is why the context of shared resources becomes extremely convenient.

This is how I extended the ribbon by adding a button (visible when the user is composing a mail):

In the OfficeTab section – I will create a new tab group in the ribbon with the Group tag. By adding tags like Label, Tooltip and Control in there – I can tell Outlook what I want my tab group to contain. The Control tag is the actual add-in command, right now we support buttons and menus.

Much like in the tab group, I can add labels and tooltips to the button. But I can also include icons and hook up an add-in command action (the function name that I created in the functions file – in other words: onCommandClick).

If you would simply like to just launch your add-in when a user clicks on the add-in command (button), you can create a ShowTaskpane action (instead of ExecuteFunction) like this:

Remember to create a resource of the type Url, with the corresponding identifier – that holds the path to the HTML file to launch when a user clicks on the add-in command.

I’m using and referencing a lot of resources in the ExtensionPoint – again this is good practice. This is what my Resources tag looks like:

Now – launching the add-in with the extended manifest in Outlook 2016 will display the add-in command in the mail creation flow. Voila!

mycommand

Additional resources
If you didn’t know there is a GitHub repository named OfficeDev – which contains a ton of useful samples and best practices! There is also a sample for Outlook add-in commands available at: https://github.com/OfficeDev/Outlook-Add-in-Commands-Translator

Do check out these places if you would like to learn more. With that, you can start creating add-in commands for your Outlook add-ins. As we make progress and support add-in commands across more flavors of Outlook – they will start popping up. It is a great way of getting users access to your functionality with a simple click!

Here is the completed manifest file for your convenience:

-Simon Jäger