JAVASCRIPT
Integrating React into Microsoft Office
A guide on how to turn your React app into Microsoft Office add-in
Microsoft Office products such as Word, Excel, PowerPoint, etc. are used to solve many everyday tasks. But not everyone knows that these applications can use Add-ins available from Microsoft AppSource. These add-ons allow you to extend the standard Office functionality, such as translating text, searching for images on the Internet, or even scheduling Starbucks appointments. It’s worth noting that many modern add-ins work with Office for iPad, Office Online, and Office for Mac, not just the traditional desktop versions of Office for Windows.
I needed to integrate a widget to work with an existing website I wrote earlier. The main tasks of the add-in can be divided into the following points:
- getting data from an open Microsoft Office document into a widget context;
- analysis of the received data from the current document, highlighting keywords using a simple NLP algorithm (counting the most used words, excluding prepositions and conjunctions), as well as searching for these words and displaying the corresponding content (cards with different types of content: text, images, video, questionnaires, etc.), via the API of an already written server;
- the ability to quickly insert content from search results into the working area of the document.
To implement our own Office add-in, we need to prepare two main components — a manifest file and a web application.
The manifest is an XML file that defines the following parameters and capabilities of the add-in:
- The display name, description, id, version, and locale of the add-in by default.
- How the add-in is integrated with Office.
- Permission level and data access requirements for the add-in.
A web application is an HTML page that is displayed in an Office application. Any technology, both client-side and server-side, can be used to generate code that interacts with Office documents and allows the user to interact with web resources from an Office application. In turn, Microsoft provides JavaScript Office.js APIs for interacting with documents. It looks like this:
Before starting development, Microsoft Office suggests that you familiarize yourself with, and accordingly adhere to, the following design principles for add-ins:
- Design specifically for Office.
- Focus on a few key tasks.
- Content is more important than chrome (appearance).
- Make the add-on experience enjoyable and let users choose what to do.
- Support for all platforms and input methods.
Microsoft also developed Office UI Fabric, the official front-end framework for creating interfaces in Office. And of course, he recommends using it when developing.
Writing a manifest file
First, let’s prepare a manifest file. The following diagram shows the hierarchy of members used to define add-in commands.
We split the entire manifest file into 3 parts:
- General information about the add-in — here you can see the name, version, description of the add-in, etc., as well as the supported platform types in our add-in (available: Word, Excel, PowerPoint, Outlook, Project, and SharePoint).
- Next is an information block for each platform type that we have announced. This contains information for a specific type. Example for Word:
- In the last part, we describe the resource information block:
Detailed information on creating a manifest file can be found in the official documentation .
Writing a web application
To develop a web application, we need a JavaScript API for Office. The Office JavaScript API library consists of an Office.js file and associated JS files. The easiest way to reference the API is to use a Content Delivery Network (CDN) by adding the following code <script>to the <head>page tag :
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>
To start working with the library, you need to initialize the Office library, for this there is a method Office.onReady()- this is an asynchronous method that returns a Promise object when checking that the Office.js library is loaded. When the library is loaded, the Promise object maps, as the object that defines the Office application, to the numeric value Office.HostType (Excel, Word, etc.), and the platform maps to the numeric value Office.PlatformType (PC, Mac, OfficeOnline, etc.) .d.). The Promise is matched immediately if the library is already loaded when it is called Office.onReady().
Add-ins interact with objects in Office using two types of JavaScript object models:
The Office Common JavaScript API is used if you need to:
- create add-ins for Word 2013;
- perform the initial steps for the application;
- check the supported set of requirements;
- get access to document metadata, its parameters and information about the environment;
- create a binding to sections of the document and record events;
- use custom XML parts;
- open a dialog box.
JavaScript APIs for Excel, Word, PowerPoint provide strongly typed objects that can be used to access various objects in the document workspace.
For example, to get content from the document workspace, you can use the method getSelectedDataAsync:
And to insert content into the workspace, we can use the method setSelectedDataAsync:
I would also like to highlight the use of the Dialog API in Office add-ins. It is currently supported for Word, Excel, PowerPoint, and Outlook. Dialog API allows you to implement:
- Display a login page that cannot be opened directly in the task pane.
- Provide more screen space (or even the entire screen) for some tasks in the add-in.
- Post a video that is too small in the task pane.
It is important to note that the web application page and dialog resources must have the same FQDN.
In general, any web technology and framework can be used to create a web application. Since I was developing an add-on for a ready-made website, I chose React as the client framework, just like in the main site, I also used the API of a ready-made backend written in Ruby. As a result, I got such an add-on, which can be found in the public domain, although it will come in handy if you are a user of the ProjectX platform.
At the moment, AppSource contains about 6.5 thousand ready-made applications, divided into specific categories and industries. Microsoft continues to develop and support this direction by making it easier to create add-ons and extending the Office.js JavaScript APIs. There are many helpful development resources on the Microsoft site . Ultimately, before an add-in is released to the public, it must pass the testing phase and must meet all the requirements to run Microsoft Office Add-ins .
Read More
If you found this article helpful, click the💚 or 👏 button below or share the article on Facebook so your friends can benefit from it too.
