context (Mailbox requirement set 1.9)

Office.context

Office.context provides shared interfaces that are used by add-ins in all of the Office apps. This listing documents only those interfaces that are used by Outlook add-ins. For a full listing of the Office.context namespace, see the Office.context reference in the Common API.

Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read

Properties

Property Modes Return type Minimum
requirement set
auth Compose
Read
Auth IdentityAPI 1.3
contentLanguage Compose
Read
String 1.1
diagnostics Compose
Read
ContextInformation 1.5
displayLanguage Compose
Read
String 1.1
host Compose
Read
HostType 1.5
mailbox Compose
Read
Mailbox 1.1
platform Compose
Read
PlatformType 1.5
requirements Compose
Read
RequirementSetSupport 1.1
roamingSettings Compose
Read
RoamingSettings 1.1
ui Compose
Read
UI 1.1

Property details

auth: Auth

Supports single sign-on (SSO) by providing a method that allows the Office application to obtain an access token to the add-in's web application. Indirectly, this also enables the add-in to access the signed-in user's Microsoft Graph data without requiring the user to sign in a second time. See IdentityAPI 1.3 requirement set.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version N/A
Applicable Outlook mode Compose or Read
Example
Office.context.auth.getAccessTokenAsync(function(result) {
    if (result.status === "succeeded") {
        const token = result.value;
        // ...
    } else {
        console.log("Error obtaining token", result.error);
    }
});



contentLanguage: String

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

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

Type
  • String
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read
Example
function sayHelloWithContentLanguage() {
  const 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: ContextInformation

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

Note

For all Mailbox requirement sets, you can also use the Office.context.mailbox.diagnostics property to get similar information.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.5
Applicable Outlook mode Compose or Read
Example
const contextInfo = Office.context.diagnostics;
console.log("Office application: " + contextInfo.host);
console.log("Office version: " + contextInfo.version);
console.log("Platform: " + contextInfo.platform);



displayLanguage: String

Gets the locale (language) in RFC 1766 Language tag format specified by the user for the UI of the Office client application.

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

Type
  • String
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read
Example
function sayHelloWithDisplayLanguage() {
  const 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;
}



host: HostType

Gets the Office application that is hosting the add-in.

Note

Alternatively, you can use the Office.context.diagnostics property to get the platform. For all Mailbox requirement sets, you can also use the Office.context.mailbox.diagnostics property to get similar information.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.5
Applicable Outlook mode Compose or Read
Example
console.log(JSON.stringify(Office.context.host));



platform: PlatformType

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

Note

Alternatively, you can use the Office.context.diagnostics property to get the platform. For all Mailbox requirement sets, you can also use the Office.context.mailbox.diagnostics property to get similar information.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.5
Applicable Outlook mode Compose or Read
Example
console.log(JSON.stringify(Office.context.platform));



requirements: RequirementSetSupport

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

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read
Example
console.log(JSON.stringify(Office.context.requirements.isSetSupported("mailbox", "1.1")));



roamingSettings: 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 Outlook client used to access that mailbox.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Minimum permission level restricted
Applicable Outlook mode Compose or Read



ui: UI

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your Office Add-ins.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.1
Applicable Outlook mode Compose or Read