Office Add-In with Knockout.js

Lately I have been investigating the new Office add-ins (the ones built on open web tech). Alongside the other additions to the Office platform; Unified APIs and AD apps they present a great surface area for solving higher level business productivity scenarios. Add to that Office’s 1.2B customers and the fact that Office now runs on the major mobile platforms makes this a powerful proposition. I have been gradually implementing samples for various different angles around the tech and thought it might help others to read about my experiences. First a little bit of background:

Add-Ins

Add-ins are a way to extend Office applications such as Word, Excel, etc. by providing a rendered surface onto one of a few possible integration points. The different options are Task Pane Add-In, Mail Add-In, Content Add-In or Add-In Command and a great description of the different types can be found here Add-Ins Platform Overview. The Add-Ins can be hosted inside the standalone/desktop apps or from within Office365 or Outlook Web App and as the platform progresses more host environments come online for each different add-in type; I refer back to Office applications that support Office Add-ins for the updated matrix. I’m going to show how I built a Task Pane Add-In which brings content from Github into Word, Excel, etc. This diagram shows the architecture for an add-in:

 

Note that the web technologies and hosting are whatever you want them to be and access to the Office document model is provided via Office.js and there is a very clear security boundary between client and cloud as the content is hosted within iframes and calls to and from the object model are marshalled via postMessage. In addition, you need a manifest which is an xml file which describes your app to the store.

Getting Started

There are a few different ways to get started with this:

If you have Visual Studio 2015 installed and you ticked the ‘Microsoft Office Developer Tools’ option when you installed then you are good to go.

If you have Visual Studio 2013 then you can add the tools from here Office Developer Tools for Visual Studio 2013

You can use NAPA – an online IDE. https://www.napacloudapp.com/Getting-Started (you need a Microsoft Account to log in here).

OR

Use the Yeoman generator (yo office) http://dev.office.com/blogs/creating-office-add-ins-with-any-editor-introducing-yo-office for a more lightweight experience. When I am on my mac I like to use the Yeoman generator with Visual Studio Code but insert your editor of choice here.

We really only need to generate the manifest really and have a way to upload this into the client application for debugging. If you use Visual Studio here then it will automate that for you so is convenient. You can also set up an add-in catalog and then debug your add-in from within the browser using the F12 developer tools.

Code

For this example I started out with Visual Studio and when you hit File > New Project

You get this option (be careful the naming convention for add-ins was previously App!).

The project wizard gives you a choice for the kind of Add-in you want to develop.

After generating we get a solution with two projects; one holding the manifest and one for an example web app. The example app is good to get started with but here you can point the manifest at any web url and develop your add-in that way. I used the sample app (which includes Office.js and some css) and added some scripts.I wanted a way to get some data from Github to email or add to Excel and imagined that it would fit nicely into a wider development team scenario. So, I discovered Github.js https://github.com/michael/github and along with Knockout.js and the Office UI Fabric I had all of the moving parts for my Add-In. 

Knockout allows you to declaratively data bind a view model to HTML which is a concept I favour having done a lot of XAML data binding in the past. So I created a ViewModel using ko.observable which retrieved that data from Github (using Github.js). I then simply bound the data to my HTML page for display within the Add-In. This data could then be transformed into table form for injecting into the Office document at the users cursor. I allowed tables for a project summary, contributors and number of contributions and a commit list.

Here’s the javascript to inject the contributors table into the Office doc:

And here’s the HTML showing the declarative databinding:

The project can be found here https://github.com/UKDXOfficeDev/o365-github-addin