Xylos brands

How to build an Office add-in

Have you ever used Office add-ins? These plug-in applications add handy features that help you use Office software more efficiently. At Xylos, we’ve built our own Office add-in for OASE. In this blog post, I’ll explain how we developed it.

1. Het OASE-scenario

Are you familiar with our online learning platform OASE? It contains over 1,000 instructional videos and other items to support users of Office 365 (Word, Excel, Outlook) in the workplace. The tutorials on the platform enable them to learn while they’re working and teach them how to use certain applications more efficiently.

The web platform has a powerful search and filter engine with which users can look up the content they need quickly. OASE’s dynamic language settings are another major advantage: users can select the spoken language and the language used in the software shown in the videos.

But the OASE team never sits still; they’re always looking for ways to help users find content even more quickly and easily. One of the suggestions that popped up was to create an Office add-in that shows OASE in a task pane to the side of the software window, so that users no longer need to switch to a browser to use OASE. So, how exactly does one build an add-in like this? 

Word with OASE add-in

2. Using HTML, CSS and JavaScript

At first, we thought we’d need to use outdated technologies, but the opposite was true. Since Office add-ins are basically web applications, we’d be able to do the job with trusted technologies such as HTML, CSS and JavaScript.

Yeoman generator for Office add-ins

To get started, we used the Yeoman generator for Office add-ins (Node.js required). This command-line tool lets you effortlessly generate a new add-in project with a JavaScript framework of your choice. You’re actually creating two basic components in one go:

  • A web application
  • A manifest file

In our case, the website was built with Angular. We needed to make sure that its layout is sized correctly for the task pane and scales nicely to adjust to the available space. It’s important to note that we’re using the JavaScript API for Office. The Office JavaScript library is initialised before the actual Angular application is started up:

Code example: loading Office & Angular

This ensures that the website can only load in an Office application. After the website has loaded, you can use the library in the entire Angular app. There are several interaction options, some of which are specific to the host application (like Word, Excel or PowerPoint). For example: you can execute a calculation on a selected cell in your Excel worksheet or change the font of your Word document.

For our OASE add-in, we only needed some of the functionalities that are ‘shared’ between several Office applications. For example: by reading Office.context.displayLanguage, the add-in automatically adjusts the software language used in the videos, and Office.context.host lets the user filter content by application. These features enhance the user experience and ensure that different Office 365 components can use the same add-in.

3. What is a manifest file?

A manifest file is an XML configuration file that defines the add-in’s properties, such as the web app’s URL, the name of the add-in, button icons for the top bar, and the necessary permissions. For each host application (Word, Excel, ...), you add a separate section with the desired configuration.

Example of a manifest file

There are several ways to load an Office add-in. When developing the add-in, you could choose to sideload it, for example. To do this, you put the manifest file in a shared folder, after which you can manually load it into one of your Office applications. As soon as the add-in is ready for production, you can publish it in the public store (after validation). Do note that we’re using Centralized Deployment: as soon as an administrator uploads the manifest file through the Office 365 administration centre, the users in the organisation involved automatically see the add-in in their software window.

You can also use the command line to validate a manifest file and check whether your adjustments are working properly before you continue testing.

Office add-in, piece of cake?

Of course, not everything went flawlessly during the development of our add-in. While setting it up was generally unproblematic, there were some hiccups.

One of the problems we encountered was the fact that we couldn’t play videos in full-screen mode, and the add-in task pane itself was too narrow to display the video properly. To solve this issue, we chose to work with a pop-up window. The Dialog API, which is part of the Office JavaScript API, proved to offer the most efficient solution.

Add-in pop-up video

We also needed to make creative use of the API’s possibilities. Trivial things such as defining the ideal pop-up screen size and supporting events in Angular (e.g. closing the pop-up window) weren’t as easy as they might seem. Luckily, you’ll have an easier time if you want to start developing an Angular Office add-in now, because most Angular-related particulars have now been documented by Microsoft.

Additionally, OASE users need to log into the add-in – but the web pages that are required for the authentication process are different for every organisation, and every website used needs to be mentioned in the manifest file’s ‘AppDomains’. If a web page isn’t included here, users will automatically open it in an external browser when they try to access it, making it impossible to complete the login process in the add-in. To solve this, we created a separate manifest file for each organisation. This is one of the reasons why we chose Centralized Deployment for our add-in.

Cookies and HTML5 web storage are retained, which means that users don’t have to log in every time they open the add-in.

Conclusion

Building an Office add-in is an adventure. With a good scenario and a bit of creativity, you can achieve great results. Do you want to try it yourself? With some knowledge of HTML and JavaScript, you’ll take off in no time.

Do you want to know more about our video platform OASE or do you have any questions about our Office add-in project? Don’t hesitate to contact our experts. They’ll gladly help you.

Share this blogpost

Leave a reply

Your email address will not be published. Required fields are marked.