How to: Determine host application support for specific API members

apps for Office

How to use if statements to determine whether a host application supports specific objects, methods, and enumerations of the JavaScript API for Office (Office.js)

Last modified: June 30, 2014

Applies to: Access app for SharePoint | Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook for Mac for Office 365 | Outlook Web App | OWA for Devices | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 | Project 2013 SP1 | Word 2013 | Word 2013 RT | Word 2013 SP1

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

In this article
Determining if a host application supports an API member
Example: Conditionally adding controls to the UI of your app
Additional resources

You can use an if statement in the script of an app to determine if the host application supports a given object, method, or enumeration in the JavaScript API for Office. For example, to determine if a host application supports the CustomXmlParts object and its members, you can use an if statement in this form:

if(Office.context.document.customXmlParts){
// Code to run if true.
}

This code will execute if the app is running in the context of Word 2013, which supports the CustomXmlParts object, but won't execute if the app is running in the context of Excel 2013 or Excel Online.

To determine if a host application supports a specific method, use an if statement in this form:

if(Office.context.document.bindings.addFromPromptAsync){
// Code to run if true.
}

This code will execute if the app is running in the context of Excel 2013, which supports the bindings.addFromPromptAsync method, but won't execute if the app is running in the context of Word 2013.

To determine if a host application supports a specific enumeration, use an if statement in this form:

if(Office.CoercionType.Ooxml){
// Code to run if true.
}

This code will execute if the app is running in the context of Word 2013, which supports the Office.CoercionType.Ooxml value of the CoercionType enumeration when specified in a method such as the Binding.setDataAsync method, but won't execute if the app is running in the context of Excel 2013 or Excel Online.

In the following example, the if statement determines if the host application supports the Document.setSelectedDataAsync method, which enables writing data to the document. If so, the setData function is added as the click event handler of the button control with an id of "setDataBtn". If not, the button control is removed. This is useful if you are creating a task pane app that targets Excel, Word, and Project. Because Project doesn't support the setSelectedDataAsync method, the "setDataBtn" button will be removed from the page when the app is running in Project. However, if the app is running in Excel or Word, which do support the setSelectedDataAsync method, the control will be available to write data to the document.

Office.initialize = function (reason) {
    // Checks for the DOM to load.
    $(document).ready(function () {
        $("#getDataBtn").click(function () { getData("selectedData"); });

        // Checks if setSelectedDataAsync is supported and adds appropriate click handler.
        if (Office.context.document.setSelectedDataAsync) {
            $("#setDataBtn").click(function () { setData("Sample data"); });
        }
        // Remove.
        else {
            $("#setDataBtn").remove();
        }
    });
}
Show:
© 2014 Microsoft