Customize Office for the web with CheckFileInfo properties
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 Copycontains the most recent document edits, even when theDownloadUrlis 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.
Breadcrumb properties
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
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 |
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 |