Office.Context interface

Represents the runtime environment of the add-in and provides access to key objects of the API. The current context exists as a property of Office. It is accessed using Office.context.

Remarks

HostsAccess, Excel, Outlook, PowerPoint, Project, Word

Properties

commerceAllowed

True, if the current platform allows the add-in to display a UI for selling or upgrading; otherwise returns False.

contentLanguage

Gets the locale (language) specified by the user for editing the document or item.

diagnostics

Gets information about the environment in which the add-in is running.

displayLanguage

Gets the locale (language) specified by the user for the UI of the Office host application.

document

Gets an object that represents the document the content or task pane add-in is interacting with.

host

Contains the Office application host in which the add-in is running.

license

Gets the license information for the user's Office installation.

mailbox

Provides access to the Outlook Add-in object model for Microsoft Outlook and Microsoft Outlook on the web.

Namespaces:

  • diagnostics: Provides diagnostic information to an Outlook add-in.

  • item: Provides methods and properties for accessing a message or appointment in an Outlook add-in.

  • userProfile: Provides information about the user in an Outlook add-in.

[ API set: Mailbox 1.0 ]

officeTheme

Provides access to the properties for Office theme colors.

platform

Provides the platform on which the add-in is running.

requirements

Provides a method for determining what requirement sets are supported on the current host and platform.

roamingSettings

Gets an object that represents the custom settings or state of a mail add-in saved to a user's mailbox.

The RoamingSettings object lets you store and access data for a mail add-in that is stored in a user's mailbox, so that is available to that add-in when it is running from any host client application used to access that mailbox.

[ API set: Mailbox 1.0 ]

touchEnabled

Specifies whether the platform and device allows touch interaction. True if the add-in is running on a touch device, such as an iPad; false otherwise.

ui

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes.

Property Details

commerceAllowed

True, if the current platform allows the add-in to display a UI for selling or upgrading; otherwise returns False.

commerceAllowed: boolean;

Property Value

boolean

Remarks

The iOS App Store doesn't support apps with add-ins that provide links to additional payment systems. However, Office Add-ins running on the Windows desktop or for Office Online in the browser do allow such links. If you want the UI of your add-in to provide a link to an external payment system on platforms other than iOS, you can use the commerceAllowed property to control when that link is displayed.

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this enumeration.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for iPad
Excel Y
Word Y

contentLanguage

Gets the locale (language) specified by the user for editing the document or item.

contentLanguage: string;

Property Value

string

Remarks

The contentLanguage value reflects the Editing Language setting specified with File > Options > Language in the Office host application.

In content add-ins for Access web apps, the contentLanguage property gets the add-in culture (e.g., "en-GB").

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this enumeration.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y Y

Examples

function sayHelloWithContentLanguage() {
    var myContentLanguage = Office.context.contentLanguage;
    switch (myContentLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

diagnostics

Gets information about the environment in which the add-in is running.

diagnostics: ContextInformation;

Property Value

displayLanguage

Gets the locale (language) specified by the user for the UI of the Office host application.

displayLanguage: string;

Property Value

string

Remarks

The returned value is a string in the RFC 1766 Language tag format, such as en-US.

The displayLanguage value reflects the current Display Language setting specified with File > Options > Language in the Office host application.

In content add-ins for Access web apps, the displayLanguage property gets the add-in language (e.g., "en-US").

When using in Outlook, the applicable modes are Compose or read.

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this enumeration.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y

Examples

function sayHelloWithDisplayLanguage() {
    var myDisplayLanguage = Office.context.displayLanguage;
    switch (myDisplayLanguage) {
        case 'en-US':
            write('Hello!');
            break;
        case 'en-NZ':
            write('G\'day mate!');
            break;
    }
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

document

Gets an object that represents the document the content or task pane add-in is interacting with.

document: Office.Document;

Property Value

Remarks

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this enumeration.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y Y

Examples

// Extension initialization code.
var _document;

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
    // After the DOM is loaded, code specific to the add-in can run.
    // Initialize instance variables to access API objects.
    _document = Office.context.document;
    });
}

host

Contains the Office application host in which the add-in is running.

host: HostType;

Property Value

license

Gets the license information for the user's Office installation.

license: string;

Property Value

string

mailbox

Provides access to the Outlook Add-in object model for Microsoft Outlook and Microsoft Outlook on the web.

Namespaces:

  • diagnostics: Provides diagnostic information to an Outlook add-in.

  • item: Provides methods and properties for accessing a message or appointment in an Outlook add-in.

  • userProfile: Provides information about the user in an Outlook add-in.

[ API set: Mailbox 1.0 ]

mailbox: Office.Mailbox;

Property Value

Remarks

Minimum permission levelRestricted
Applicable Outlook modeCompose or read

Examples

// The following line of code access the item object of the JavaScript API for Office.
var item = Office.context.mailbox.item;

officeTheme

Provides access to the properties for Office theme colors.

officeTheme: OfficeTheme;

Property Value

Examples

function applyOfficeTheme(){
    // Get office theme colors.
    var bodyBackgroundColor = Office.context.officeTheme.bodyBackgroundColor;
    var bodyForegroundColor = Office.context.officeTheme.bodyForegroundColor;
    var controlBackgroundColor = Office.context.officeTheme.controlBackgroundColor
    var controlForegroundColor = Office.context.officeTheme.controlForegroundColor;

    // Apply body background color to a CSS class.
    $('.body').css('background-color', bodyBackgroundColor);
}

platform

Provides the platform on which the add-in is running.

platform: PlatformType;

Property Value

requirements

Provides a method for determining what requirement sets are supported on the current host and platform.

requirements: RequirementSetSupport;

Property Value

roamingSettings

Gets an object that represents the custom settings or state of a mail add-in saved to a user's mailbox.

The RoamingSettings object lets you store and access data for a mail add-in that is stored in a user's mailbox, so that is available to that add-in when it is running from any host client application used to access that mailbox.

[ API set: Mailbox 1.0 ]

roamingSettings: Office.RoamingSettings;

Property Value

Remarks

Minimum permission levelRestricted
Applicable Outlook modeCompose or read

touchEnabled

Specifies whether the platform and device allows touch interaction. True if the add-in is running on a touch device, such as an iPad; false otherwise.

touchEnabled: boolean;

Property Value

boolean

Remarks

Use the touchEnabled property to determine when your add-in is running on a touch device and if necessary, adjust the kind of controls, and size and spacing of elements in your add-in's UI to accommodate touch interactions.

Support details

A capital Y in the following matrix indicates that this property is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this enumeration.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Supported hosts, by platform

Office for iPad
Excel Y
PowerPoint Y
Word Y

ui

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes.

ui: UI;

Property Value