Edit

Share via

context (Mailbox preview requirement set)

  • Article

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
officeTheme Compose
Read		 OfficeTheme 1.14
platform Compose
Read		 PlatformType 1.5
requirements Compose
Read		 RequirementSetSupport 1.1
roamingSettings Compose
Read		 RoamingSettings 1.1
sensitivityLabelsCatalog Compose SensitivityLabelsCatalog 1.13
ui Compose
Read		 UI 1.1
urls Compose
Read		 Urls 1.14

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.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version Preview
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 host. 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));

officeTheme: OfficeTheme

Provides access to the properties for Office theme colors.

Note

This member is only supported in Outlook on Windows.

Using Office theme colors lets you coordinate the color scheme of your add-in with the current Office theme selected by the user with File > Office Account > Office Theme UI, which is applied across all Office client applications. Using Office theme colors is appropriate for mail and task pane add-ins.

Type
Properties
Name Type Description
bodyBackgroundColor String Gets the Office theme body background color as a hexadecimal color triplet.
bodyForegroundColor String Gets the Office theme body foreground color as a hexadecimal color triplet.
controlBackgroundColor String Gets the Office theme control background color as a hexadecimal color triplet.
controlForegroundColor String Gets the Office theme body control color as a hexadecimal color triplet.
Requirements
Requirement Value
Minimum mailbox requirement set version Preview
Applicable Outlook mode Compose or Read
Example
function applyOfficeTheme(){
  // Get office theme colors.
  const bodyBackgroundColor = Office.context.officeTheme.bodyBackgroundColor;
  const bodyForegroundColor = Office.context.officeTheme.bodyForegroundColor;
  const controlBackgroundColor = Office.context.officeTheme.controlBackgroundColor
  const controlForegroundColor = Office.context.officeTheme.controlForegroundColor;

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

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

sensitivityLabelsCatalog: SensitivityLabelsCatalog

Gets the object to check the status of the catalog of sensitivity labels in Outlook and retrieve all available sensitivity labels if the catalog is enabled.

Type
Requirements
Requirement Value
Minimum mailbox requirement set version 1.13
Minimum permission level read/write item
Applicable Outlook mode Compose

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

urls: Urls

Gets the object to retrieve the runtime URLs of an add-in.

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

Events

You can subscribe to and unsubscribe from the following events using addHandlerAsync and removeHandlerAsync respectively.

Event Description Minimum
requirement set
OfficeThemeChanged The Office theme in Outlook changed. Only available with task pane implementation. 1.14