Customizing Office Online using CheckFileInfo properties

You can customize the user interface and experience of Office Online by using a combination of CheckFileInfo properties as well as by implementing the PostMessage API.

CheckFileInfo properties

CloseUrl

If provided, when the Close UI is activated, Office Online will navigate the outer page (window.top.location) to the URI provided.

Hosts can also use the ClosePostMessage property to indicate a PostMessage should be sent when the Close UI is activated rather than navigate to a URL, or set the CloseButtonClosesWindow property to indicate that the Close UI should close the browser tab or window (window.top.close).

If the CloseUrl, ClosePostMessage, and CloseButtonClosesWindow properties are all omitted, the Close UI will be hidden in Office Online.

Note

The Close UI will never be displayed when using the embedview action.

See also

CloseUrl in the WOPI REST documentation.

DownloadUrl

If a DownloadUrl is not provided, Office Online will hide all UI to download the file.

If provided, Word and PowerPoint Online will display UI to download the file. When a user attempts to download the file, Word and PowerPoint will ensure that the latest document content is saved back to the WOPI host before navigating the user to the DownloadUrl to download the file.

Excel Online Note

Excel Online does not use the DownloadUrl when users click the Download a Copy button. Excel Online always downloads the file directly from the Office Online server. This has the following side effects:

  1. Any content that Excel Online does not currently support, such as diagrams, are stripped from the downloaded file.
  2. Excel Online does not guarantee that the latest document content is saved back to the WOPI host before downloading the file.
  3. Download a Copy contains all the most recent document edits, even when the DownloadUrl is implemented incorrectly and does not point to the latest version of the document.

See also

DownloadUrl in the WOPI REST documentation.

FileSharingUrl

If provided, when the Share UI is activated, Office Online will open a new browser window to the URI provided.

Hosts can also use the FileSharingPostMessage property to indicate a PostMessage should be sent when the Share UI is activated rather than navigate to a URL.

If neither the FileSharingUrl nor the FileSharingPostMessage properties are set, the Share UI will be hidden in Office Online.

See also

FileSharingUrl in the WOPI REST documentation.

HostEditUrl

This URL is used by Office Online to navigate between view and edit mode.

See also

HostEditUrl in the WOPI REST documentation.

HostViewUrl

This URL is used by Office Online to navigate between view and edit mode.

See also

HostViewUrl in the WOPI REST documentation.

SignoutUrl
If this property is not provided, no sign out UI will be shown in Office Online.

See also

SignoutUrl in the WOPI REST documentation.

CloseButtonClosesWindow

If set to true, Office Online will close the browser window or tab (window.top.close) when the Close UI in Office Online is activated.

If Office Online displays an error dialog when booting, dismissing the dialog is treated as a close button activation with respect to this property.

Hosts can also use the CloseUrl property to indicate that the outer frame should be navigated (window.top.location) when the Close UI is activated rather than closing the browser tab or window, or set the ClosePostMessage property to indicate a PostMessage should be sent when the Close UI is activated.

If the CloseUrl, ClosePostMessage, and CloseButtonClosesWindow properties are all omitted, the Close UI will be hidden in Office Online.

Note

The Close UI will never be displayed when using the embedview action.

See also

CloseButtonClosesWindow in the WOPI REST documentation.

Breadcrumb properties
Office Online displays all of the Breadcrumb properties if they are provided.

PostMessage properties

The PostMessage properties control the behavior of Office Online with respect to incoming PostMessages. Note that if you are using the PostMessage extensibility features of Office Online, you must set the PostMessageOrigin property to ensure that Office Online accepts messages from your outer frame. You can read more about PostMessage integration at Using PostMessage to interact with the Office Online application iframe.

In cases where a PostMessage is triggered by the user activating some Office Online UI, such as FileSharingPostMessage or EditModePostMessage, Office Online will do nothing when the relevant UI is activated except send the appropriate PostMessage. Thus, hosts must accept and handle the relevant messages when the Office Online UI is triggered. Otherwise the Office Online UI will appear to do nothing when activated.

If the PostMessage API is not supported (e.g. the user’s browser does not support it, or the browser security settings prohibit it, etc.), Office Online UI that triggers a PostMessage will be hidden.

ClosePostMessage

A Boolean value that, when set to true, indicates the host expects to receive the UI_Close PostMessage when the Close UI in Office Online is activated.

Hosts can also use the CloseUrl property to indicate that the outer frame should be navigated (window.top.location) when the Close UI is activated rather than sending a PostMessage, or set the CloseButtonClosesWindow property to indicate that the Close UI should close the browser tab or window (window.top.close).

If the CloseUrl, ClosePostMessage, and CloseButtonClosesWindow properties are all omitted, the Close UI will be hidden in Office Online.

Note

The Close UI will never be displayed when using the embedview action.

EditModePostMessage

A Boolean value that, when set to true, indicates the host expects to receive the UI_Edit PostMessage when the Edit UI in Office Online is activated.

If this property is not set to true, Office Online will navigate the inner iframe URL to an edit action URL when the Edit UI is activated.

EditNotificationPostMessage
A Boolean value that, when set to true, indicates the host expects to receive the Edit_Notification PostMessage.
FileSharingPostMessage

A Boolean value that, when set to true, indicates the host expects to receive the UI_Sharing PostMessage when the Share UI in Office Online is activated.

Hosts can also use the FileSharingUrl property to indicate that a new browser window should be opened when the Share UI is activated rather than sending a PostMessage. Note that the FileSharingUrl property will be ignored completely if the FileSharingPostMessage property is set to true.

If neither the FileSharingUrl nor the FileSharingPostMessage properties are set, the Share UI will be hidden in Office Online.

FileVersionPostMessage

A Boolean value that, when set to true, indicates the host expects to receive the UI_FileVersions PostMessage when the Previous Versions UI (File ‣ Info ‣ Previous Versions) in Office Online is activated.

Hosts can also use the FileVersionUrl property to indicate that a new browser window should be opened when the Previous Versions UI is activated rather than sending a PostMessage. Note that the FileVersionUrl property will be ignored completely if the FileVersionPostMessage property is set to true.

If neither the FileVersionUrl nor the FileVersionPostMessage properties are set, the Previous Versions UI will be hidden in Office Online.

PostMessageOrigin

A string value indicating the domain the host page will be sending/receiving PostMessages to/from. Office Online will only send outgoing PostMessages to this domain, and will only listen to PostMessages from this domain.

Office Online Tip

This value will be used as the targetOrigin when Office Online uses the HTML5 Web Messaging protocol. Therefore, it must include the scheme and host name. If you are serving your pages on a non-standard port, you must include the port as well. The literal string *, while supported in the PostMessage protocol, is not allowed by Office Online.

WorkflowPostMessage

Pre-release property - not yet used by any WOPI client

A Boolean value that, when set to true, indicates the host expects to receive the UI_Workflow PostMessage when the Workflow UI in Office Online is activated.

Hosts can also use the WorkflowUrl property to indicate that a new browser window should be opened when the Workflow UI is activated rather than sending a PostMessage. Note that the WorkflowUrl property will be ignored completely if the WorkflowPostMessage property is set to true.

If neither the WorkflowUrl nor the WorkflowPostMessage properties are set, the Workflow UI will be hidden in Office Online.

Important

This value will be ignored if WorkflowType is not provided.

Customizing the Office Online viewer UI using CheckFileInfo

The following table describes all available buttons and UI in the Office Online viewer and what CheckFileInfo properties can be used to remove them.

Button How to disable
Edit in Browser

Two options:

  1. (preferred) Set UserCanWrite to false in the CheckFileInfo response (or omit it since the default for all boolean properties in CheckFileInfo is false)
  2. Omit the HostEditUrl and EditModePostMessage properties from the CheckFileInfo response
Share Omit the FileSharingUrl and FileSharingPostMessage properties from the CheckFileInfo response
Download / Download as PDF Omit the DownloadUrl property from the CheckFileInfo response
Print Set the DisablePrint property to true in the CheckFileInfo response
Exit / Close Omit the CloseUrl and ClosePostMessage properties from the CheckFileInfo response
Comments

For Word only, set the UserCanWrite property to false in the CheckFileInfo response (or omit it since the default for all boolean properties in CheckFileInfo is false)

Can’t be hidden in PowerPoint

Find Can’t be hidden
Translate Can’t be hidden
Help Can’t be hidden
Give Feedback Can’t be hidden
Terms of Use Can’t be hidden
Privacy and Cookies Can’t be hidden
Accessibility Mode Can’t be hidden
Start Slide Show Can’t be hidden
Embed Omit the HostEmbeddedViewUrl and HostEmbeddedEditUrl properties from the CheckFileInfo response
Refresh Selected Connection Can’t be hidden
Refresh All Connections Can’t be hidden
Calculate Workbook Can’t be hidden
Save a Copy Set the UserCanNotWriteRelative property to true in the CheckFileInfo response