Posted by on Feb 29, 2016 in #Office365Dev | 0 comments

With the new application model for Office comes a brand new way of extending Office with your own functionality – using the tools and dev stacks that we already know and love.

This blog post demonstrates a few different ways to interact with the Office context. Accessing different types of data for a mailbox item (message or appointment) in read mode. In addition, Different styles and components from the Office UI Fabric library are used throughout this Office add-in.
The objective is to get familiar with some of the possiblities that we have when building Outlook add-ins.

The blog post is divided into multiple steps and should be followed in a chronological order. These are the included steps:

1.1 Create the project
1.2 Edit the manifest
1.3 Launch the project
2.1 Clean up the project
2.2 Add Office UI Fabric
2.3 Add the base
3.1 Add the dialog
4.1 Get the item subject
4.2 Get the item sender
4.3 Get the item body

Short of time and just want the final sample? Clone this repository (https://github.com/simonjaeger/OfficeDev-HOL.git) and open the solution file: Read-Mode-Outlook-Add-in\Source\Read-Mode-Outlook-Add-in.sln.

Prerequisites

Visual Studio 2015: https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx
Office Developer Tools: https://www.visualstudio.com/en-us/features/office-tools-vs.aspx
Office 2013 (Service Pack 1) or Office 2016
Office 365 Developer Tenant: http://dev.office.com/devprogram

Step 1.1: Create the project

The first thing that we need to do is to create the project itself. Make sure that you have installed all of the required prerequisites before launching Visual Studio 2015.

1. Click File, New and finally the Project button.
2. In Templates, select Visual C#, Office/SharePoint and then Office Add-ins. This will list the Office add-in templates, choose Office Add-in.
3. Name your project “Read-Mode-Outlook-Add-in” and click the OK button to continue.

4. Next up Visual Studio 2015 will need a bit more information about what you are going to create – in order to set up the required files. Your next step is to decide which type of Office add-in that you want to create. Depending on what you pick, your Office add-in will run in different Office applications and contexts.

For this blog post, we will create a mail add-in – this means that our Office add-in will run in in Outlook as a view beside the Office context (e.g. a message or appointment). Select Mail and click on Next.

5. Finally we need to choose the supported modes for our mail add-in. This means that we are defining the contexts that our mail add-in can run within; read, compose or both. If you choose Read form, the mail add-in will be able to run when a user is viewing a mailbox item. In Compose form, the mail add-in can run when a user is creating or editing a mailbox item.

In our case, select Read form for both Email message and Appointment. Deselect everything else to create a read mode mail add-in. Click Finish to complete the wizard.

6. Using the information you specified in the wizard, Visual Studio 2015 will configure your project. Have a look in the Solution Explorer and find your two new projects in the Read-Mode-Outlook-Add-in solution.

Read-Mode-Outlook-Add-in: This is your manifest project, containing the XML manifest file. This is basically a representation of the information you just specified while creating your Office add-in project.

Read-Mode-Outlook-Add-inWeb: This is your web project for the Office add-in. This contains all of the different source files that makes up your Outlook add-in. We will make quite a few adjustments to this structure as we continue.

You’ve now created the basic structure for a mail add-in running in Outlook.

Step 1.2: Edit the manifest

We need to make sure that we understand the manifest file. This file is essential for your add-in; it tells Office where everything is hosted (locally throughout this blog post) and where it can be launched. So let’s open it and edit the manifest file.

1. In the manifest project Read-Mode-Outlook-Add-in, double-click the Read-Mode-Outlook-Add-inManifest file. This will open the manifest editor.

2. In the General tab section, find and edit the Display name and Provider name to anything you’d like.

3. In the Read Form tab section, find the Activation part. This is what determines the rules for potential activation of your mail add-in. By default, both Item is a message and Item is an appointment should be included.
4. Scroll down and pay attention to the Source location property. This points to a specific file in your web project (Read-Mode-Outlook-Add-inWeb). When launching your mail add-in, this page will be the first thing that gets loaded and displayed.

Step 1.3: Launch the project

Before we launch our mail add-in we should validate that our start actions are proper.

1. Select the manifest project; Read-Mode-Outlook-Add-in in the Solution Explorer.

2. In the Properties window, set Start Action to Office Desktop Client.
4. Set Web Project to your web project; Read-Mode-Outlook-Add-inWeb.

5. To launch the project, open the Debug menu at the top of Visual Studio 2015 and click on the Start Debugging button. You can also click the Start button in your toolbar or use the {F5} keyboard shortcut.

6. When launching your mail add-in for the first time, Visual Studoo 2015 needs to install the manifest file. This is where you should use your Office 365 Developer Tenant (if you haven’t signed up for one yet, get yours for free at http://dev.office.com/devprogram). Enter the credentials of a user ([username]@[your domain].onmicrosoft.com) belonging to your Office 365 Developer Tenant and click on the Connect button.

7. Once Outlook has launched, you’ll notice that your mail add-in doesn’t start right away. We need to start it manually. Select a message in your mailbox (send yourself one if needed) and click on the Read-Mode-Outlook-Add-in above it. Once your mail add-in has launched, you can explore the functionality that comes right out of the box with the Visual Studio 2015 template.

8. Finally, stop debugging by opening the Debug menu at the top of Visual Studio 2015 and click on the Stop Debugging button. You can also click the Stop button in your toolbar.

Step 2.1: Clean up the project

While the default styling that comes along with the Visual Studio 2015 template for Office add-ins does its job – leveraging the features of the Office UI Fabric can be fantastic. It’s a UI toolkit made specifically for building Office and Office 365 experiences, so it will certainly help us out here.

The Office UI Fabric library comes with everything from styling, components to animations. The majority of the library can be references via a CDN. The heavier parts needs to be downloaded and added to the project itself. We will go through both of these approaches.

Our first task is to clean up the project, and remove the default styling and setup.

1. Remove the Content and Images folders from the web project. You can do this by right-clicking these folders in the Solution Explorer and choosing the Delete option.

2. In your Solution Explorer, find the Home.html file – which is the startup page for your mail add-in. Remove everything inside the body tags.
3. In Home.html remove the CSS reference to “../../Content/Office.css” – we have removed this file and will be using Office UI Fabric instead. This should leave you with this:

4. In App.js, remove the initialize() function defined on the app object, as this will not be used:

5. In Home.js, remove the displayItemDetails() function and the call to app.initialize(). We are remaking the structure of the mail add-in, these will no longer be used. You should end up with this:

6. In App.css, remove everything, leaving you with an empty file.
7. In Home.css, remove everything, leaving you with an empty file.

Step 2.2: Add Office UI Fabric

1. In Home.html, add two CSS references to the CDN for Office UI Fabric inside the head tags. Add them before the CSS reference to “../App.css”.

2. Your Home.html file should now look like this:

Step 2.3: Add the base (CSS + HTML)

1. In App.css, add the following basic CSS (this should be entire file). We will do much of the styling through already defined classes in the Office UI Fabric. But some basic layouting will do us great!

2. In Home.html, add the following chunk of HTML inside the body tags. This will set the stage for the next array of steps to come.

3. Launch your mail add-in to display the new styling. We will add more interactive components in the different sections (inside the recently added HTML piece).

Step 3.1: Add the dialog

As we are going to extract property values from the mailbox item, let’s have a more sophisticated approach than the JavaScript Console. We can use an Office UI Fabric dialog to display this data in a more user-friendly way.

1. In Home.html, locate the “Step: Data dialog” comment and add the following HTML piece below it. This is an Office UI Fabric styled dialog.

2. Launch your mail add-in and test your work. You should find a dialog covering up most of your display area.

3. In Home.js, add two event handlers (below the initialization of the Office UI Fabric components, in the ready function) for the dialog. This will allow us to close it.

4. In Home.js, add the following functions to show and close the dialog:

5. Launch your mail add-in and test your work. You should be able to close the dialog using any of the two buttons.
6. In Home.css, add the following CSS piece to hide the dialog when your mail add-in has launched.

Step 4.1: Get the item subject

1. In Home.html, locate the “Step: Get subject” comment and add the following HTML piece below it. This is an Office UI Fabric styled button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following function to get the item subject (below the Office.initialize function):

4. Launch your mail add-in and test your work by clicking the Get subject button. When the button is clicked, the function will be executed; displaying the item subject using the data dialog.

Step 4.2: Get the item sender

1. In Home.html, locate the “Step: Get sender” comment and add the following HTML piece below it. This is an Office UI Fabric styled button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following function to get the item sender (below the Office.initialize function):

4. Launch your mail add-in and test your work by clicking the Get sender button. When the button is clicked, the function will be executed; displaying the item sender using the data dialog.

Step 4.3: Get the item body

1. In Home.html, locate the “Step: Get body” section comment add the following HTML piece below it. This is an Office UI Fabric styled button.

2. In Home.js, add an event handler (below the initialization of the Office UI Fabric components, in the ready function) for the click event of the button:

3. In Home.js, add the following function to get the item body (below the Office.initialize function):

4. Getting the item body is an asynchronous function that requires a minimum mailbox requirement set version of 1.3. There are different ways of ensuring that your user has at least version 1.3, a good way is to set it in the manifest.

In the manifest project Read-Mode-Outlook-Add-in, double-click the Read-Mode-Outlook-Add-inManifest file. This will open the manifest editor.

5. In the General tab section, find the Mailbox requirement set property and set it to 1.3.

4. Launch your mail add-in and test your work by clicking the Get body button. When the button is clicked, the function will be executed; displaying the item body using the data dialog.

Wrap up

View the source code files included in this blog post for a final reference of how your code should be structured (if needed). You should now have grasped an understanding of a few possibilities of interacting with the Office context (a mailbox item in this case). In addition, you have also seen some of the styles and components included in the Office UI Fabric.

-Simon Jaeger