Customizing Office for the web using CheckFileInfo properties

You can customize the user interface and experience of Office for the web 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 for the web 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 for the web.

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 for the web will hide all UI to download the file.

If provided, Word and PowerPoint for the web 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 for the web Note

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

  1. Any content that Excel for the web does not currently support, such as diagrams, are stripped from the downloaded file.

  2. Excel for the web 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 for the web 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 for the web.

See also

FileSharingUrl in the WOPI REST documentation.

HostEditUrl

This URL is used by Office for the web to navigate between view and edit mode.

See also

HostEditUrl in the WOPI REST documentation.

HostViewUrl

This URL is used by Office for the web 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 for the web.

See also

SignoutUrl in the WOPI REST documentation.

CloseButtonClosesWindow

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

If Office for the web 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 for the web.

Note

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

See also

CloseButtonClosesWindow in the WOPI REST documentation.

Breadcrumb properties

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

PostMessage properties

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

In cases where a PostMessage is triggered by the user activating some Office for the web UI, such as FileSharingPostMessage or EditModePostMessage, Office for the web 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 for the web UI is triggered. Otherwise the Office for the web 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 for the web UI that triggers a PostMessage will be hidden.

AppStateHistoryPostMessage

A Boolean value that, when set to true, indicates the host outer frame supports the use of HTML5 Session History. The outer frame should then expect to receive App_PushState PostMessages and propagate onpopstate events to Office for the web through the App_PopState PostMessage.

OneNote for the web Note

This message is only used by OneNote for the web and is thus not needed to integrate with Office for the web or Office for iOS. It is included for completeness but does not need to be implemented.

OneNote for the web integration is not included in the Office 365 - Cloud Storage Partner Program.

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 for the web is activated.

Hosts should 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 for the web.

Important

The CloseUrl must always be provided in order for the Close UI to appear in Office for the web, even if ClosePostMessage is true.

Most PostMessage-related properties do not require that the corresponding URL property be provided in order to enable the relevant UI in Office for the web. CloseUrl is an exception to this.

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 for the web is activated.

If this property is not set to true, Office for the web 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.

FileEmbedCommandPostMessage

A Boolean value that, when set to true, indicates the host expects to receive the UI_FileEmbed PostMessage when the Embed UI in Office for the web is activated.

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

If neither the FileEmbedCommandUrl and the FileSharingPostMessage properties are set, the Embed UI will be hidden in Office for the web unless a HostEmbeddedViewUrl is provided in CheckFileInfo.

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 for the web 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 for the web.

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 for the web 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 for the web.

PostMessageOrigin

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

Office for the web Tip

This value will be used as the targetOrigin when Office for the web 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 for the web.

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 for the web 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 for the web.

Important

This value will be ignored if WorkflowType is not provided.

Best practices when using PostMessage properties

The WOPI protocol is designed for use in a variety of scenarios and environments. While PostMessage is a useful integration technique for web-browser-based WOPI clients such as Office for the web, it is not usable in other WOPI clients, such as Office for iOS.

To provide maximum compatibility with all types of WOPI clients, hosts should set corresponding URL properties when using PostMessage properties. For example, when setting FileSharingPostMessage to true, hosts should also provide a FileSharingUrl. This will enable a WOPI client that cannot use PostMessage to navigate the user to a URL that will allow them to manage sharing the file.

While the primary reason to provide corresponding URL properties for PostMessage properties is for non-browser-based WOPI clients, there are legitimate reasons to do this for Office for the web as well. In particular, users may use browsers that do not support PostMessage. While all officially supported Office for the web browsers do support PostMessage, when users use unsupported browsers Office for the web strives to give the user the best possible experience. Providing the URL properties enables users to use Office for the web features even in browsers where PostMessage won’t work.

Customizing the Office for the web viewer UI using CheckFileInfo

The following table describes all available buttons and UI in the Office for the web 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