MS Office

The Word Adapter allows apps to use MS Word as a document editor. The app sends document text and images to Word in the form of HTML, so that the user may edit it using a familiar tool. When the user saves the changes, a new HTML document is created and sent back to the app to display and/or store in the backend where it can be properly secured and audited.

Summary of features:

• The HTML document is sent to the app every time the user saves the document.
• Images may be embedded within the document HTML, as long as they are in one of the following formats: PNG, ICO, BMP, or JPEG.
• Embedded objects, such as images, charts and spreadsheets can be added to the Word document, but these will be converted to inline HTML images before they are returned to the app. The original objects can be preserved in Microsoft DOCX format, however, and can be saved to the backend so the user can edit the document later.
• Documents are created in the folder %AppData%\Tick42\GlueWordPad\Files (configurable).

As shown in the Setup section, you need to initialize the @glue42/office library and set the word property of the configuration object to true:

const config = {
    // ...,
    word: true // enable Word integration
}

After that, get a reference to the Word Adapter API:

Glue4Office(config)
    .then(office => {
        const word = office.word
        // interact with Word
    })
    .catch(console.error)

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.onClosed(doc => closeDocumentPreviewFor(doc));

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