How does the sample Outlook Add-in work?

In this article I will describe how the out of the box Outlook Add-in created in the previous article works.

Introduction

In the previous article I showed how we can create an outlook Add-in, out of the box in less than 30 minutes. In this article we will take a look at how the Add-in actually works. That will in turn allow us to create our own in the future.

The Add-in

The Add-in itself is build up of a number of different parts which we will look at in turn. As this is a Read only app we will not look into the AppCompose folder as none of that is used in this Add-in

n1

Home.html

The Home.html represents the core of the Add-in and as you can see from the image – it is a complete HTML file

n2

I say complete HTML file not to be facetious but to highlight what the Add-in really is. It is a self contained web application which has contextual information available from the parent Email. To better understand this, if we look at the way the Add-in is created within the interface, it should make more sense.

How the Add-in works (Nov 2015)

This is very likely to change over time, so contextually in November 2015 this is how it works. When you click on the Add-in link within the email an iframe is created within the website – the URL of that is the Add-in itself.

Looking at the DOM through Chrome Dev Tools we can see the Add-in and nothing else underneath it

n3

When we click on the Marky Websockets (which will make sense in a later article) we can then see the new iFrame created

n4

Clicking on the URL and opening the iFrame source in a new window reveals the basic building blocks of the Add-in

https://www.napacloudapp.com/Run/d4f76aa8055344fca71c06bc35fb43b6/aHR0cHM6Ly9wc2NsaXN0ZW5zMS5zaGFyZXBvaW50LmNvbS9zaXRlcy9tYXJreS1kZXY/AppRead/Home/Home.html?et=&_host_Info=Outlook|Web|16.00#&_xdm_Info=-1b68cff0_-3d7d1568_1446597857415|ocii1|https://outlook.office365.com/owa/?realm=psclistens.com#path=/mail

n5

Viewing the source – it looks just like what we saw as home.html in the napa cloud app – cos it is !!!

n6

Once we start to think of the Add-in as it’s own iframe running application we can start to envision all sorts of things we can do here….but more on that later.

Within home.html we load a number of files:

n7

  • jQuery – nothing special there
  • office.js – this is the core of the Office Add-in technology, it creates the interface for the whole Add-in, both from the iframe creation to the iframe gaining the details from the parent.
  • App.js – this file creates some display functionality within the context of the app
  • Home.js – this is the file which creates the contents of the Add-in, within the context of the parent email (the actual Add-in code)

office.js

Well I would love to explain how this works – but it is rather obfuscated…..https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js – I am going to have to piece this together over time – but for right now, let’s just go with – that is what makes all these unicorns and rainbows work……what I can tell is that it is loading a whole load of other libraries as well. It is not the only magic box.

App.js

Once the application is loaded within the app, this Immediately-Invoked Function Expression (IIFE) runs and creates the HTML for a notification popup, and appends it to the bottom of the Add-in within the iframe

n8

 

Within the DOM of the iframe contents we can see the planted classname clearly. This notification will be called when we click on the name of the sender in the Add-in.

n9

Home.js

Home.js creates the interface from the Add-in to the information in the parent email.

n10

This IIFE code comes in three sections:

  • Office.initialize
    • This is the code which triggers the office Add-in – it states that in the jQuery document.ready even call these two functions
  • app.initialize
    • This calls the initialize function() created within App.js
  • displayItemDetails()
    • This is a function which we will go into further

displayItemDetails()

The “Office” namespace is used through all the Add-in codebase and precedes all the JavaScript API calls

In this function the code uses the Office.cast.item , which is actually superfluous. If you look at the link you will see that it is used within Visual Studio to achieve Intellisense for the real code which is “var item = Office.context.mailbox.item;”. The function can be simplified to the following

n11

As you can see from the code above I have added a console.log(item) to see what we are getting here. Contained within the item object we can see other objects and the first one contains a lot of the information available within the JavaScript API

n12

Further down the console.log we are able to see “functions” within the object

n13

thus in our code – item.from actually calls the namespaced function within the item object, that then parses the object and collects the from information (see previous image)

Going back to the home.js code – this finall uses some jQuery to

  1. $(‘#from’).text(from.displayName);
    • Add the “displayName” to the id named from within home.html

n14

  1. $(‘#from’).click(function () {
    app.showNotification(from.displayName, from.emailAddress);
    });

    • When you click on the item within the from DIV the app.showNotification is called passing in the name and emailAddress

n15

 

Conclusion

In this article we have taken a rather exhaustive look at exactly how the sample Outlook Add-in works. I believe that with a better understanding of how the underlying application functionality work, we are able to better harness it’s power in the future.

In the next article I will look at how to manipulate the contents of the sample and start to build something with purpose.

 

Advertisements

2 thoughts on “How does the sample Outlook Add-in work?

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