Mail Apps 101, a Directions app

Office 365 now (well, for a little while now) supports a new kind of app, written in user friendly Javascript. This is cool because:

  • Add-ins (as opposed to Apps) were just really complicated and messy, requiring the use of COM among other things.
  • Where Add-in’s were a .net/C++ hybrid, Apps are written in Javascript. This means they can run in the web portal for Office as well as on the native desktop apps.
  • There’s a store. This makes distribution of your app much easier. Also, you can get paid.

I’m going to document the process of making a basic directions app for Outlook (which will run on OWA, Outlook native, and now Outlook on android and ios!).

Goals:

  • Build an app to assist in composing emails/meetings by providing a maps-experience to add directions, destinations, and map pictures to an email.
  • Get the app in the store.
  • Keep it simple, rather than build something overbearing, lets just glue some spikes together.

Ingredients:

  • Bing Maps Javascript-Embedded API  – So we can have a map experience within the app.
  • Bing Maps Routes API – So we can get route / location data
  • Bing Maps Static-Maps API – So we can embed a picture of the map nicely into the email.

Spikes:

Lets make some basic spikes, first lets just make a basic hello-world compose app. For this, we’ll need the manifest which is used to install the app, and the app itself, which will be a basic HTML page.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <title>Directions Spike</title>
    <script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"
            type="text/javascript"></script>
    <script type="text/javascript">
        Office.initialize = function (reason) {
            if (Office.context.mailbox.item !== null) {
                document.getElementById('haveItemSpan').innerText
                    = 'we have an item!';
            }
        };
    </script>
</head>
<body>
    <span id="haveItemSpan"></span>
</body>
</html>

Our app is going to be running in an iFrame type environment. We reference office.js, as it provides all the objects and API’s we’ll use to interact with the compose form. Office.initialize is a function pointer, and we point it to the function we want to be called to initialize our app (our constructor). If we didn’t assign this, our app would not load and a yellow error-bar would appear.

You’ll notice above that we reference version 1.1 of the office.js file. We also specify below in the manifest.xml that MinVersion=1.1. Version 1.0 of these API’s only supported read-item level access. Access to compose (edit) functionality was provided in 1.1.

In the manifest, we specify the host to be mailbox. This is so the office store knows what kind of app this is. We need to request the read-write item permission, so that we can later add our data to the message/meeting being composed. We also provide a source-url to where we host our app (the URL I provided here is fictitious).

Lastly, the rule-collection settings determine when the app would fire. We have specified that we only want this to open when editing (composing) messages and appointments.

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:type="MailApp">
  <Id>d65f2ab9-7ce6-4b70-96a8-1af331f7e2d5</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>flacnut</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Directions" />
  <Description DefaultValue="Directions spike app."/>
  <Hosts>
    <Host Name="Mailbox" />
  </Hosts>
  <Requirements>
    <Sets>
      <Set Name="MailBox" MinVersion="1.1" />
    </Sets>
  </Requirements>
  <FormSettings>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <SourceLocation DefaultValue="http://yourhost.com/spike_index.html"/>
      </DesktopSettings>
    </Form>
  </FormSettings>
  <Permissions>ReadWriteItem</Permissions>
  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" />
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit" />
  </Rule>
  <DisableEntityHighlighting>false</DisableEntityHighlighting>
</OfficeApp>

The result of these two things is this. Yay!

Our basic app spike

The adventure continues in the next article, as we tackle some basic Bing Maps sikes.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: