Microsoft Office

The @glue42/office library provides the necessary instrumentation for your web apps to interoperate with Word when the Word Adapter is installed and running. The library is available as an NPM package and is also distributed as JavaScript files with io.Connect Desktop. The files are located in the <installation_location>/interop.io/io.Connect Desktop/SDK/ioOfficeJS/js/web-bundle folder.

To install the @glue42/office library, execute the following command:

npm install @glue42/office

You can now import the factory function exposed by the library:

import Glue4Office from "@glue42/office";

You can also reference the library as a JavaScript file in the HTML file of your web app using a <script> tag:

<script type="module" src="./office.min.js"></script>

The @glue42/office library exposes a global factory function called Glue4Office which you must invoke to initialize the library in your app. The factory function accepts an optional Config which you can use to configure various features of the library.

The following sections provide examples which demonstrate how to initialize the @glue42/office library and access the Word API in JavaScript, React, and Angular apps. It's generally recommended to expose a reference to the API object returned when the Glue4Office factory function resolves and then render your app.

JavaScript

Initializing the @glue42/office library in a JavaScript app:

import Glue4Office from "@glue42/office";

// Optional configuration for the library.
const config = {
    // Disabling the Excel and Outlook APIs.
    excel: false,
    outlook: false
};

//Initializing the library and obtaining a reference to the API object.
const office = await Glue4Office(config);

// Now the Word API is accessible via the `office.word` object.

React

Initializing the @glue42/office library in a React app:

import { createRoot } from "react-dom/client";
import Glue4Office from "@glue42/office";
import App from "./App";

// Expose the API object as a global variable which you can use in all your components.
// The Word API will then be accessible via the `office.word` object.
window.office = await Glue4Office();

const domElement = document.getElementById("root");
const root = createRoot(domElement);

root.render(<App />);

Angular

Initializing the @glue42/office library in an Angular app:

import { bootstrapApplication } from "@angular/platform-browser";
import { appConfig } from "./app/app.config";
import { App } from "./app/app";
import Glue4Office from "@glue42/office";

// Expose the API object as a global variable which you can use in all your components.
// The Word API will then be accessible via the `office.word` object.
window.office = await Glue4Office();

bootstrapApplication(App, appConfig);

When io.Connect Desktop is initialized, you can check whether Word is running and the Word Adapter is loaded:

console.log(`The Word Adapter is ${word.addinStatus ? "available" : "unavailable"}`);

You can use the onAddinStatusChanged() method to track the availability of the Word Adapter. You may find this useful if you need to track when to enable or disable certain elements of your app user interface.

const unsubscribe = word.onAddinStatusChanged(available => {
    console.log(`The Word Adapter is ${available ? "available" : "unavailable"}`)
});

The available argument passed to your callback will be true if and only if:

• Word is running.
• The Word Adapter is installed and enabled in Word.
• The Word Adapter and your app are using the same connectivity configuration and are connected to the same io.Connect Gateway.

In any other case, the available flag will be false.

To stop listening for connection status changes, simply call the returned function:

unsubscribe();

Typically, you would have some contents formatted as HTML in your web app and would like to let the user edit this in Word. When the user updates the document, you may want to get the changes back into your app.

Most of the time this is works, because HTML can express lots in terms of formatting. However, certain objects in Word, such as WordArt, embedded Excel spreadsheets, etc., don't have a round-trip representation in HTML and are automatically converted to images by Word. That is why the Word Adapter API lets you send dually formatted documents back and forth between your app and Word - one in HMTL format, which is used to display the document, and another in DOCX (the Word XML document format) which you send from your app to Word so you can keep the original objects editable.

Creating New Documents

To create a document with your app contents, call the openDocument() method of the Word Adapter API, passing the name of the document and its HTML representation packed in a OpenDocumentConfig object:

const htmlContents = document.getElementById("contents").innerHTML;

word.openDocument({
    data: htmlContents
    })
    .then(wordDoc => console.log("Document created"))
    .catch(console.error)

The Promise returned by the openDocument() method resolves with a reference to a Document object. If you are planning on tracking any updates performed by the user, you will need to keep a reference to the opened document.

Preventing Save of Temporary Documents

If your users need to edit data in Word, but aren't allowed to save it locally and should instead return the data to be saved in your app, you can set the inhibitLocalSave flag to true, which will prevent the users from saving the temporary document.

Opening Existing Documents

If you already have a document in your app which you want to let the user edit, you would most certainly want to send the DOCX version to Word, not the HTML one, so that Word can work with the original document and preserve WordArt, embedded Excel sheets and so on, as the document circulates between Word and your app:

fetchDocument()
.then(docxData => word.openDocument({
    data: docxData
    })
)
.then(wordDoc => console.log("Document loaded"))
.catch(console.error)

Once you have obtained a reference to the opened document, you can subscribe for and start tracking updates by the user using the onChanged() method of the Document object:

word.openDocument({
        data: document.getElementById("contents").innerHTML
    })
    .then(wordDoc => {
        console.log("Document created");

        wordDoc.onChanged((html, docx) => {
            document.getElementById("contents").innerHTML = html;
            postSave(docx)   // save document to backend
        })
    })
    .catch(console.error)

You can see from the example above that the onChanged() callback will be called with both an HMTL representation of the document, which you can render in your app, as well as the DOCX version of the document (represented as Base64 string) which you can send to your backend for audit/storage purposes.

There are some occasions when you want to be notified when the user closes the document in Word or even exits Word. You can subscribe for such a change using the onClose() method of the Document object received by the openDocument() call:

wordDoc.onClose(doc => closeDocumentPreviewFor(doc));

For a complete list of the available Word Adapter API methods and properties, see the Word Adapter Reference Documentation.