Sharepoint 2013 : The Office JavaScript Object Model (part 1) - Document-based Apps

The Office JavaScript Object Model provides the ability for your web application and the Office host application to interact, and that’s where the creativity and innovation of your web-based solution can intersect with the creativity and innovation of the Office user.

You can think of Apps for Office in two ways: those that will interact with documents (document based) and those that will interact with mail items (mailbox based). At the time of this writing, document-based apps include Word, Excel, PowerPoint, and Project. The xsi:type TaskPaneApp and ContentApp are document-based apps for Office. The mailbox-based app, xsi:type MailApp, is, of course, associated with the Outlook rich client and companion Outlook Web App (OWA). Therefore, although the Office JSOM is a unified object model, due to the differences between the sheer nature of a document and a mailbox item, you will use different parts of the Office API depending on which Office applications your app for Office will target.

Fortunately, you do not need to build the manifest file and all the constituent parts in a raw text editor for an app for Office as you did in the previous Try It Out, but you instead have the power of Visual Studio to make this job much less tedious. With the Apps for Office tools installed in Visual Studio, the File ⇒ New Project process is a guided experience that automatically generates an appropriate manifest file for a TaskPaneApp, ContentApp, or MailApp. You then have an immediate F5, debug runtime experience. Of course, you can go on to fine-tune and customize the manifest and build out your app, but Visual Studio provides for you a solid starting point.

Document-based Apps

The Office JSOM provides many capabilities for document-based apps for Office. With Office JSOM, your web application can programmatically interact with a selection the user has made, read or write to your document, react to events as the user enters a specific location or changes data in the document, save one or more settings in the document so that they are persisted for the next time the document is opened, and much more. However, the thing to keep in mind, especially for those who have written VBA or built add-ins in the past, is that the Office JSOM is not for automation of the Office client itself, but for enabling programmatic interaction between the document and your task pane or content app. Everything you do using the Office JSOM is focused around the user and the document, and should enable that experience to be a productivity gain for the user.

The Microsoft.Office.WebExtension namespace contains the JavaScript objects needed to programmatically interact with the Office client applications that support Apps for Office. In code, this namespace is referred to by the alias Office. The Visual Studio app for Office project template includes the Office.js library in the Scripts/Lib folder for the Web project. Figure 1 shows the core objects in the API.

FIGURE 1

The main objects you will use for document-based apps are Office, .context, and .document. When your App for Office is specific to Microsoft Outlook, then you will use the .mailbox object to access the APIs specific to programming against the mail client — but this object is covered in further detail later. If you are creating Apps for Office specifically for Microsoft Project, you will use the .project part of the Office API.

To keep this discussion straightforward, for Microsoft Word and Excel, the document object provides the functional capabilities needed for document interaction. With this you can read and write an active selection, bind to named locations in the document, and react to events at the document or bound-location level. Almost all methods in the Office JSOM are asynchronous to not tie up the UI as your method call executes. A typical line of code used to retrieve the data the user has selected in the document looks like this:

Office.context.document.getSelectedDataAsync(...)

Although not a lot of methods are in the API, they provide the fundamental building blocks for you to build your solution — it’s up to your imagination on how you stitch them together to meet a business need. Let’s now explore what Visual Studio provides for Apps for Office and explore the API.

    <button onclick="writeToDoc()"> Write to Document </button><br/>
    <button onclick="readFromSelection()"> Read from Document Selection 
    </button><br/>
    <button onclick="bindToData()"> Bind to User-selected Data </button><br/>
    <button onclick="readFromBoundData()"> Read from Bound Data </button><br/>
    <button onclick="addAnEvent()"> Add an Event </button><br/>
    <span>Show: </span><div id="show"></div>

Office.initialize = function (reason) {
    $(document).ready(function () {
        showResult('Document Ready');
    });
};
 
function writeToDoc() {
    Office.context.document.setSelectedDataAsync([["apples"], 
["pears"], ["oranges"], ["cherries"]], function (asyncResult) {
        if (asyncResult.status === "failed") {
            showResult('Error: ' + asyncResult.error.message);
        }
    });
}
 
function readFromSelection() {
    Office.context.document.getSelectedDataAsync("matrix", 
function (asyncResult) {
        if (asyncResult.status === "failed") {
            showResult('Error: ' + asyncResult.error.message);
        }
        else {
            showResult('Read from Selection: ' + asyncResult.value);
        }
    });
}
 
function bindToData() {
    Office.context.document.bindings.addFromSelectionAsync("matrix", 
{ id: 'fruitBinding' },
        function (asyncResult) {
            if (asyncResult.status === "failed") {
                showResult('Error: ' + asyncResult.error.message);
            } else {
                showResult('A binding type of ' + asyncResult.value.type
                    + ' was added with an id of ' +
                    asyncResult.value.id);
            }
        });
}
 
function readFromBoundData() {
    Office.select("bindings#fruitBinding").getDataAsync({ 
coercionType: "matrix" },
        function (asyncResult) {
            if (asyncResult.status === "failed") {
                showResult('Error: ' + asyncResult.error.message);
            } else {
                showResult('Value of bound selection: ' + asyncResult.value);
            }
        });
}
 
function addAnEvent() {
    Office.select("bindings#fruitBinding").addHandlerAsync(
"bindingDataChanged", fruitHandler, function (asyncResult) {
        if (asyncResult.status === "failed") {
            showResult('Error: ' + asyncResult.error.message);
        } else {
            showResult('New event handler added for binding.');
        }
    });
}
function fruitHandler(eventArgs) {
    eventArgs.binding.getDataAsync({ coerciontype: "matrix" }, 
function (asyncResult) {
 
        if (asyncResult.status === "failed") {
            showResult('Error: ' + asyncResult.error.message);
        } else {
            showResult('Show bound data change: ' + asyncResult.value);
        }
    });
}
 
function showResult(text) {
    document.getElementById('show').innerText = text;
}