Posted by on Mar 1, 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. Setting different properties of a mailbox item (message or appointment) in compose 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 Set the item subject
3.2 Set the item recipients
3.3 Set 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: Compose-Mode-Outlook-Add-in\Source\Compose-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 “Compose-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 Compose form for both Email message and Appointment. Deselect everything else to create a compose 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 Compose-Mode-Outlook-Add-in solution.

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

Compose-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 Compose-Mode-Outlook-Add-in, double-click the Compose-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 Compose Form tab section, find the Activation part. This is what determines the potential activation of your mail add-in. By default, both Email messages and Appointments should be checked.
4. Pay attention down below to the Source location property. This points to a specific file in your web project (Compose-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; Compose-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; Compose-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. Create a new message and click on the Office Add-ins button.

8. Select Compose-Mode-Outlook-Add-in and click Start.

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

10. 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 setSubject(), getSubject() and addToRecipients() functions (and the corresponding click event handler registrations in the document.ready function).
6. In Home.js, remove 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: Set the item subject

1. In Home.html, locate the “Step: Set subject” section (commented) and add the following HTML piece inside the div (section) tags. 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 functions to set the item subject (below the Office.initialize function):

4. Launch your mail add-in and test your work by clicking the Set subject button. When the button is clicked, the function will be executed; setting the item subject in the mailbox item.

Step 3.2: Set the item recipients

1. In Home.html, locate the “Step: Set recipients” section (commented) and add the following HTML piece inside the div (section) tags. 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 set the item recipients:

4. Launch your mail add-in and test your work by clicking the Set recipients button. When the button is clicked, the function will be executed; setting the item recipients of the mailbox item.

Step 3.3: Set the item body

1. In Home.html, locate the “Step: Set body” section (commented) and add the following HTML piece inside the div (section) tags. 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 set the item body (below the Office.initialize function):

4. Setting 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 Compose-Mode-Outlook-Add-in, double-click the Compose-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 Set body button. When the button is clicked, the function will be executed; setting the item body.

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