How we wrote our app for MS Office 2013

Microsoft Apps for Office 2013 allows us to provide our customers with a simple way to insert their Lucidchart diagrams into Word documents. In this article, I'd like to walk you through the process of building an Office App and give a brief overview of the Lucidchart app that we released in the Microsoft Office store.

Getting started with the manifest file

The Apps for Office framework is based around a manifest file that declares the identity of the app and provides the location of the code. This means that we can build the app to run on our own web servers by providing the manifest with a URL. Having full control of our code allows us to develop faster and it makes the application more stable since we can test it more effectively. The manifest file is simply an XML file that provides enough information for Microsoft’s app store to know the app’s identity, which Office products the app can be installed in, and how to access the app:

Choose your layout

Most of the manifest file is simple to understand, but there are some important points to be thought through when creating it. When designing and building an App for Office, one of the most important decisions to make is which Office products you want your app to be available in and what type of app you will build. Context and use cases come heavily into play here. Some apps are better suited for task pane apps, where others would make far better content apps or mail apps. And don't forget, an app that makes a lot of sense in a Word document may not be as useful in Excel. We built a task pane app for Word that allows users to log in to their Lucidchart account and view their diagrams right alongside the document they are working on. In the manifest file, the type (task pane, content or mail) is specified with the xsi:type attribute of the OfficeApp tab and the supported Office products are specified by Capability tags.

SourceLocation tag

The SourceLocation tag is the key part of the manifest file, since that's where you specify the URL of the page that gets loaded into the app window. Office Apps run in an instance of Internet Explorer that has been sandboxed into the supported Office products. This is nice because the manifest can point to a URL on your own server, giving you full control of your own code at all times. The IconUrl tag points to the location of the image that will be used to identify your app in the Office store.

Permissions tag

The last part of the manifest file to point out is the Permissions tag. This specifies how your app is allowed to interact with documents. You will need Read permission if your app needs to identify selected content, and Write permissions if your app will be writing any text or ooxml to the document. Our Lucidchart app uses the ReadWriteDocument permission to write diagrams to the current selection.

The image above shows our Lucidchart app loaded right from the manifest file. The login page is going to be the first thing you see. If the user does not yet have a Lucidchart account, they can register right in the app. Once logged in, the user’s diagrams are shown in a file tree. Clicking on a diagram name will display a thumbnail preview at the bottom of the app, as seen below. 

Cookie Management

Cookies are shared between the app and the browser, so the user experience can move seamlessly between the two. When a user decides to edit a diagram that is visible in our app, they will already be logged in to their Lucidchart account when an IE browser window opens from the Office app.

We place an html button on the app page with javascript that will open the link in a browser window.

Working with the API

The API for interacting with the document through the app is just a Javascript api that can be used by including the path to the hosted .js code. The API provides all of the interaction with the document One small drawback of the API is that currently, we're only able to insert a PNG file of a user’s diagram. If the user updates the diagram later, then the image inserted into their Word document will not be updated unless they replace it manually. If the API allowed our app to insert a Quick Part with field codes into the document, then the diagrams in the document would automatically update. For now, we call setSelectedDataAsync() to insert a diagram image at the current location of the cursor in the Word document:

Last thoughts

Overall, having an Office App provides our users with more avenues for using and interacting with the diagrams that they create in Lucidchart. For our business, the app expands our discoverability by being in the Microsoft App Store. The development experience was positive and Microsoft was consistently helpful in answering questions along the way. If you would like to develop your own App for Office, head over to Microsoft’s development center. We are very eager to see how the framework grows and improves so that we can provide Lucidchart users with an even richer experience in the Word app.