Skip to content

Latest commit

 

History

History
628 lines (448 loc) · 22.5 KB

postmessage.rst

File metadata and controls

628 lines (448 loc) · 22.5 KB
Raw

Using PostMessage to interact with the application iframe

js

You can integrate your own UI into Office Online applications. This way, you can use your UI for actions on Office documents, such as sharing.

To integrate with Office Online in this way, implement the HTML5 Web Messaging protocol. The Web Messaging protocol, also known as PostMessage, allows the frame to communicate with its parent host page, and vice-versa. The following example shows the general syntax for PostMessage. In this example, otherWindow is a reference to another window that msg will be posted to.

otherWindow.postMessage(msg, targetOrigin)

param string msg

A string (or JSON object) that contains the message data.

param string targetOrigin

Specifies what the origin of otherWindow must be for the event to be dispatched. This value will be set to the PostMessageOrigin property provided in CheckFileInfo. The literal string *, while supported in the PostMessage protocol, is not allowed by Office Online.

Message format

All messages posted to and from the Office Online application frame are posted using the ~otherWindow.postMessage function. Each message (the msg parameter in the ~otherWindow.postMessage function) is a JSON-formatted object of the form:

message

MessageId (string)

The name of the message being posted.

SendTime (long)

The time the message was sent, expressed as milliseconds since midnight 1 January 1970 UTC.

Tip

You can get this value in most modern browsers using the Date.now() method in JavaScript.

Values (JSON-formatted object)

The data associated with the message. This varies per message.

The following example shows the msg parameter for the Host_PerfTiming message.

{
    "MessageId": "Host_PerfTiming",
    "SendTime": 1329014075000,
    "Values": {
        "Click": 1329014074800,
        "Iframe": 1329014074950,
        "HostFrameFetchStart": 1329014074970,
        "RedirectCount": 1
    }
}

Sending messages to the Office Online iframe

To send messages to the Office Online iframe, you must set the PostMessageOrigin property in your WOPI CheckFileInfo response to the URL of your host page. If you do not do this, Office Online will ignore any messages you send to its iframe.

You can send the following messages; all others are ignored:

  • App_PopState
  • Blur_Focus
  • CanEmbed
  • Grab_Focus
  • Host_PerfTiming
  • Host_PostmessageReady

App_PopState

The App_PopState message signals the Office Online application that state has been popped from the HTML5 History API to which the application should navigate to using the URL. This message should be triggered from an onpopstate listener in the host page.

Values

Url (string)

The URL associated with the popped history state.

State (JSON-formatted object)

The data associated with the state.

Example Message:

{
    "MessageId": "App_PopState",
    "SendTime": 1329014075000,
    "Values": {
        "Url": "https://www.contoso.com/abc123/contents?wdtarget=pagexyz",
        "State": {
            "Value": 0
        }
    }
}

Blur_Focus

The Blur_Focus message signals the Office Online application to stop aggressively grabbing focus. Hosts should send this message whenever the host application UI is drawn over the Office Online frame, so that the Office application does not interfere with the UI behavior of the host.

This message only affects Office Online edit modes; it does not affect view modes.

Tip

When the host application displays UI over Office Online, it should put a full-screen dimming effect over the Office Online UI, so that it is clear that the Office application is not interactive.

Values

Empty.

Example Message:

{
    "MessageId": "Blur_Focus",
    "SendTime": 1329014075000,
    "Values": { }
}

CanEmbed

The CanEmbed message is sent by the host in response to a request to create a HostEmbeddedViewUrl using the :jsUI_FileEmbed message.

Values

HostEmbeddedViewUrl (string)

A URI to a web page that provides access to a viewing experience for the file that can be embedded in another HTML page. This is equivalent to the HostEmbeddedViewUrl in CheckFileInfo.

Example Message:

{
    "MessageId": "CanEmbed",
    "SendTime": 1329014075000,
    "Values": {
        "HostEmbeddedViewUrl": "https://www.contosodrive.com/documents/1234/embedded/"
    }
}

Grab_Focus

The Grab_Focus message signals the Office Online application to resume aggressively grabbing focus. Hosts should send this message whenever the host application UI that is drawn over the Office Online frame is closing. This allows the Office application to resume functioning.

This message only affects Office Online edit modes; it does not affect view modes.

Values

Empty.

Example Message:

{
    "MessageId": "Grab_Focus",
    "SendTime": 1329014075000,
    "Values": { }
}

Host_PerfTiming

Provides performance related timestamps from the host page. Hosts should send this message when the Office Online frame is created so load performance can be more accurately tracked.

Values

Click (integer)

The timestamp, in ticks, when the user selected a link that launched the Office Online application. For example, if the host exposed a link in its UI that launches an Office Online application, this timestamp is the time the user originally selected that link.

Iframe (integer)

The timestamp, in ticks, when the host created the Office Online iframe when the user selected the link.

HostFrameFetchStart (integer)

The result of the PerformanceTiming.fetchStart attribute, if the browser supports the W3C NavigationTiming API. If the NavigationTiming API is not supported by the browser, this must be 0.

RedirectCount (integer)

The result of the PerformanceNavigation.redirectCount attribute, if the browser supports the W3C NavigationTiming API. If the NavigationTiming API is not supported by the browser, this must be 0.

Example Message:

{
    "MessageId": "Host_PerfTiming",
    "SendTime": 1329014075000,
    "Values": {
        "Click": 1329014074800,
        "Iframe": 1329014074950,
        "HostFrameFetchStart": 1329014074970,
        "RedirectCount": 1
    }
}

Host_PostmessageReady

Office Online delay-loads much of its JavaScript code, including most of its PostMessage senders and listeners. You might choose to follow this pattern in your WOPI host page. This means that your outer host page and the Office Online iframe must coordinate to ensure that each is ready to receive and respond to messages.

To enable this coordination, Office Online sends the App_LoadingStatus message only after all of its message senders and listeners are available. In addition, Office Online listens for the Host_PostmessageReady message from the outer frame. Until it receives this message, some UI, such as the Share button, is disabled.

Until your host page receives the App_LoadingStatus message, the Office Online frame cannot respond to any incoming messages except Host_PostmessageReady. Office Online does not delay-load its Host_PostmessageReady listener; it is available almost immediately upon iframe load.

If you are delay-loading your PostMessage code, you must ensure that your App_LoadingStatus listener is not delay-loaded. This will ensure that you can receive the App_LoadingStatus message even if your other PostMessage code has not yet loaded.

The following is the typical flow:

  1. Host page begins loading.
  2. Office Online frame begins loading. Some UI elements are disabled, because Host_PostmessageReady has not yet been sent by the host page.
  3. Host page finishes loading and sends Host_PostmessageReady. No other messages are sent because the host page hasn't received the App_LoadingStatus message from the Office Online frame.
  4. Office Online frame receives Host_PostmessageReady.
  5. Office Online frame finishes loading and sends App_LoadingStatus to host page.
  6. Host page and Office Online communicate by using other PostMessage messages.

Values

Empty.

Example Message:

{
    "MessageId": "Host_PostmessageReady",
    "SendTime": 1329014075000,
    "Values": { }
}

Listening to messages from the Office Online iframe

The Office Online iframe will send messages to the host page. On the receiving end, the host page will receive a MessageEvent. The origin property of the MessageEvent is the origin of the message, and the data property is the message being sent. The following code example shows how you might consume a message.

function handlePostMessage(e) {
    // The actual message is contained in the data property of the event.
    var msg = JSON.parse(e.data);

    // The message ID is now a property of the message object.
    var msgId = msg.MessageId;

    // The message parameters themselves are in the Values
    // parameter on the message object.
    var msgData = msg.Values;

    // Do something with the message here.
}
window.addEventListener('message', handlePostMessage, false);

The host page receives the following messages; all others are ignored:

  • App_LoadingStatus
  • App_PushState
  • Edit_Notification
  • File_Rename
  • UI_Close
  • UI_Edit
  • UI_FileEmbed
  • UI_FileVersions
  • UI_Sharing
  • UI_Workflow

Common Values

In addition to message-specific values passed with each message, Office Online sends the following common values with every outgoing PostMessage:

ui-language (string)

The LCID of the language Office Online was loaded in. This value will not match the value provided using the UI_LLCC placeholder. Instead, this value will be the numeric LCID value (as a string) that corresponds to the language used. See languages for more information.

This value may be needed in the event that Office Online renders using a language different than the one requested by the host, which may occur if Office Online is not localized in the language requested. In that case, the host may choose to draw its own UI in the same language that Office Online used.

wdUserSession (string)

The ID of the Office Online session. This value can be logged by host and used when troubleshooting <troubleshooting> issues with Office Online. See session id for more information about this value.

App_LoadingStatus

The App_LoadingStatus message is posted after the Office Online application frame has loaded. Until the host receives this message, it must assume that the Office Online frame cannot react to any incoming messages except Host_PostmessageReady.

Values

DocumentLoadedTime (long)

The time that the frame was loaded.

Example Message:

{
    "MessageId": "App_LoadingStatus",
    "SendTime": 1329014075000,
    "Values": {
        "DocumentLoadedTime": 1329014074983,
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

App_PushState

The App_PushState message is posted when the user changes the state of Office Online application in a way which the user may wish to return to later, requesting to capture it in the HTML 5 History API. In receiving this message, the Host page should using history.pushState to capture the state for a potential later state pop.

To send this message, the AppStateHistoryPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise Office Online will not send this message.

Values

Url (string)

The URL associated with the message.

State (JSON-formatted object)

The data associated with the state.

Example Message:

{
    "MessageId": "App_PushState",
    "SendTime": 1329014075000,
    "Values": {
        "Url": "https://www.contoso.com/abc123/contents?wdtarget=pagexyz",
        "State": {
            "Value": 0
        },
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

Edit_Notification

The Edit_Notification message is posted when the user first makes an edit to a document, and every five minutes thereafter, if the user has made edits in the last five minutes. Hosts can use this message to gauge whether users are interacting with Office Online. In coauthoring sessions, hosts cannot use the WOPI calls for this purpose.

To send this message, the EditNotificationPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise Office Online will not send this message.

Values

Common values <outgoing postmessage common values> only.

Example Message:

{
    "MessageId": "Edit_Notification",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

File_Rename

The File_Rename message is posted when the user renames the current file in Office Online. The host can use this message to optionally update the UI, such as the title of the page.

Note

If the host does not return the SupportsRename parameter in their CheckFileInfo response, then the rename UI will not be available in Office Online.

Values

NewName (string)

The new name of the file.

Example Message:

{
    "MessageId": "File_Rename",
    "SendTime": 1329014075000,
    "Values": {
        "NewName": "Renamed Document",
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Close

The UI_Close message is posted when the Office Online application is closing, either due to an error or a user action. Typically, the URL specified in the CloseUrl property in the CheckFileInfo response is displayed. However, hosts can intercept this message instead and navigate in an appropriate way.

To send this message, the ClosePostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise Office Online will not send this message.

Values

Common values <outgoing postmessage common values> only.

Example Message:

{
    "MessageId": "UI_Close",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Edit

The UI_Edit message is posted when the user activates the Edit UI in Office Online. This UI is only visible when using the :wopiview action.

To send this message, the EditModePostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise Office Online will not send this message and will redirect the inner iframe to an edit action URL instead.

Hosts may choose to use this message in cases where they want more control over the user's transition to edit mode. For example, a host may wish to prompt the user for some additional host-specific information before navigating.

Values

Common values <outgoing postmessage common values> only.

Example Message:

{
    "MessageId": "UI_Edit",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_FileEmbed

The UI_FileEmbed message is posted when the user activates the Embed UI in Office Online. The host should use this message to trigger the creation of a HostEmbeddedViewUrl, which the host then passes back to the WOPI client using the :jsCanEmbed message.

To send this message, the FileEmbedCommandPostMessage property in the CheckFileInfo response from the host must be set to true, and FileEmbedCommandUrl must be provided. Otherwise will not send this message.

will also not send the message if a HostEmbeddedViewUrl is provided in the CheckFileInfo response. In this case, since a HostEmbeddedViewUrl is already provided, there is no need to retrieve it from the host via PostMessage. See embedding for more details.

Values

Common values <outgoing postmessage common values> only.

Example Message:

{
    "MessageId": "UI_FileEmbed",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "en-us"
    }
}

UI_FileVersions

The UI_FileVersions message is posted when the user activates the Previous Versions UI in . The host should use this message to trigger any custom file version history UI.

To send this message, the FileVersionPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise will not send this message.

Values

Common values <outgoing postmessage common values> only.

Example Message:

{
    "MessageId": "UI_FileVersions",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Sharing

The UI_Sharing message is posted when the user activates the Share UI in Office Online. The host should use this message to trigger any custom sharing UI.

To send this message, the FileSharingPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise Office Online will not send this message.

Values

Common values <outgoing postmessage common values> only.

Example Message:

{
    "MessageId": "UI_Sharing",
    "SendTime": 1329014075000,
    "Values": {
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}

UI_Workflow

The UI_Workflow message is posted when the user activates the Workflow UI in Office Online. The host should use this message to trigger any custom workflow UI.

To send this message, the WorkflowPostMessage property in the CheckFileInfo response from the host must be set to true. Otherwise Office Online will not send this message.

Values

WorkflowType (string)

The WorkflowType associated with the message. This will match one of the values provided by the host in the WorkflowType property in CheckFileInfo.

Example Message:

{
    "MessageId": "UI_Workflow",
    "SendTime": 1329014075000,
    "Values": {
        "WorkflowType": "Submit",
        "wdUserSession": "3692f636-2add-4b64-8180-42e9411c4984",
        "ui-language": "1033"
    }
}