Share via

Customize Office for the web with CheckFileInfo properties

  • Article

You can customize the user interface and experience of Office for the web by using CheckFileInfo properties and setting up the PostMessage API.

CheckFileInfo properties

The CheckFileInfo properties follow.

CloseUrl

When the Close UI is activated, Office for the web navigates 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 omitted, the Close UI is hidden in Office for the web.

Note

The Close UI never displays when using the embedview action.

For more information, see [CloseUrl](~/rest/files/CheckFileInfo/ CheckFileInfo-Response.md#closeurl) in the WOPI REST documentation.

DownloadUrl

If a DownloadUrl isn't provided, Office for the web hides all UI to download the file.

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

Excel for the web

Excel for the web doesn't 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 effects:

  • Any content that Excel for the web doesn't currently support, such as diagrams, are stripped from the downloaded file.
  • Excel for the web doesn't guarantee that the latest document content is saved back to the WOPI host before downloading the file.
  • Download a Copy contains the most recent document edits, even when the DownloadUrl is implemented incorrectly and doesn't point to the latest version of the document.

For more information, see DownloadUrl in the WOPI REST documentation.

FileSharingUrl

If provided, when the Share UI is activated, Office for the web opens 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 is hidden in Office for the web.

For more information, see FileSharingUrl in the WOPI REST documentation.

HostEditUrl

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

For more information, see FileSharingUrl in the WOPI REST documentation.

HostViewUrl

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

For more information, see HostViewUrl in the WOPI REST documentation.

SignoutUrl

If you don't provide this property, no sign out UI is shown in Office for the web.

For more information, see SignoutUrl in the WOPI REST documentation.

CloseButtonClosesWindow

If set to true, Office for the web closes 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 omitted, the Close UI is hidden in Office for the web.

Note

The Close UI never displays when using the embedview action.

For more information, see CloseButtonClosesWindow in the WOPI REST documentation.

Office for the web displays the Breadcrumb properties if they're provided.

PostMessage properties

The PostMessage properties control the behavior of Office for the web with respect to incoming PostMessages. If you're using the PostMessage extensibility features, you must set the PostMessageOrigin property to ensure that Office for the web accepts messages from your outer frame. For more information about PostMessage integration, see 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 does 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 appears to do nothing when activated.

If the PostMessage API isn't supported (for example, the user's browser doesn't support it, or the browser security settings prohibit it, and so on), Office for the web UI that triggers a PostMessage is 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 Online

Note

This message is only used by OneNote Online and isn't required to integrate with Office for the web or Microsoft 365 for mobile. It's included for completeness but doesn't need to be implemented.

OneNote Online integration isn't 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 to 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 omitted, the Close UI is 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 don't 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.

See also

Best practices when using PostMessage properties

Note

The Close UI never displays 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 navigates 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. The FileEmbedCommandUrl property is ignored completely if the FileEmbedCommandPostMessage property is set to true.

If neither the FileEmbedCommandUrl nor the FileSharingPostMessage properties are set, the Embed UI is 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. The FileSharingUrl property is ignored completely if the FileSharingPostMessage property is set to true.

If neither the FileSharingUrl nor the FileSharingPostMessage properties are set, the Share UI is 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. The FileVersionUrl property is ignored completely if the FileVersionPostMessage property is set to true.

If neither the FileVersionUrl nor the FileVersionPostMessage properties are set, the Previous Versions UI is hidden in Office for the web.

PostMessageOrigin

A string value indicating the domain that the host page is sending and receiving PostMessages to and from. Office for the web only sends outgoing PostMessages to this domain, and only listens to PostMessages from this domain.

Tip

This value is used as the targetOrigin when Office for the web uses the HTML5 Web Messaging protocol. So, it must include the scheme and host name. If you're serving your pages on a non-standard port, you must include the port as well. The literal string *, while supported in the PostMessage protocol, isn't 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. The WorkflowUrl property is ignored completely if the WorkflowPostMessage property is set to true.

If neither the WorkflowUrl nor the WorkflowPostMessage properties are set, the Workflow UI is hidden in Office for the web.

Important

This value is ignored if WorkflowType isn't provided.

Best practices when using PostMessage properties

The WOPI protocol is designed for 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's not usable in other WOPI clients, such as Microsoft 365 for mobile.

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 enables a WOPI client that can't use PostMessage to navigate the user to a URL that does 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 might use browsers that don't support PostMessage. While all officially supported Office for the web browsers support PostMessage, when users are on unsupported browsers, Office for the web strives to give them the best possible experience. Providing the URL properties enables users to access 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 the 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
Comments Can’t be hidden
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