PostMessage API
PostMessage API is used to interact with parent frame when Collabora Online’s browser part is enclosed in one. This is useful for hosts wanting to integrate Collabora Online in them.
This API is mostly based on WOPI specification with few extensions/modifications. All messages sent are in this form :
{
"MessageId": "<MessageId>",
"SendTime": "<Timestamp when message is sent>",
"Values": {
"<key>": "<value>"
}
}
SendTime
is the timestamp returned by browsers’ Date.now(). The post messages sent from the WOPI host should also be in same form.
It is to be noted that as mentioned in WOPI specs, Collabora Online frame will ignore all post messages coming from the host frame if Host_PostmessageReady has not been received. Further, since for embedding Collabora Online as an iframe WOPI implementation is a must, it is required that PostMessageOrigin
property is present in WOPI host’s CheckFileInfo response. Otherwise, no post messages will be emitted.
Initialization
Editor to WOPI host
MessageId |
Values |
Description |
---|---|---|
|
Status: <String>
DocumentLoadedTime: <Timestamp>
|
If Status is
Accompanying keys:
Features : This client’s capabilities.Supported values are: Tells the host that client supports different version states. See Version Restore for more details When Status is completely loaded and host can also start using PostMessage API. Accompanying keys: When Status is host can show the Collabora Online frame to present an error for a user. |
WOPI host to editor
MessageId |
Values |
Description |
---|---|---|
|
See WOPI docs for detail. |
Query
You can query data from the editor using post message API. All responses are returned with query’s MessageId suffixed with ‘_Resp’ as shown below Getters
WOPI Host to Editor
MessageId |
Values |
Description |
---|---|---|
|
Queries the editor for
currently active views of
the document. Response is
returned in form of
|
|
|
Queries the editor for all the supported export formats for currently opened document. |
Getters response
Editor to WOPI host
MessageId |
Values |
Description |
---|---|---|
|
ViewId: <Number>
UserId: <String>
UserName: <String>
Color: <Number>
ReadOnly: <Boolean>
IsCurrentView: <Boolean>
|
Give details of all
current views when
queried using
|
|
Label: <String>
Format: <String>
|
Response to query
Label would contain a localized string explaining about the format. Format is the file extension of the format which is required while requesting export of the document. |
Session Management
WOPI Host to editor
MessageId |
Values |
Description |
---|---|---|
|
|
Remove the session. |
Editor to WOPI Host
MessageId |
Values |
Description |
---|---|---|
|
ViewId: <Number>
UserId: <String>
UserName: <String>
Color: <Number>
ReadOnly:<Boolean>
Deprecated: true;
|
A new member is added. |
|
ViewId: <Number>
Deprecated: true;
|
View with This message is deprecated, instead implement just
handling of |
|
See
|
Complete information about the currently connected views. |
Actions
WOPI host to editor
MessageId |
Values |
Description |
---|---|---|
|
DontTerminateEdit: <boolean>
DontSaveIfUnmodified: <boolean>
Notify: <boolean>
ExtendedData: <String>
|
Saves the document.
|
|
Filename: <String>
Notify: <boolean>
|
Creates copy of the document with given Filename.
|
|
Follow: <Boolean>
ViewId: <Number>
|
Turn on or off the follow user feature. When When |
|
Closes the document. |
|
|
Prints the document. |
|
|
Format: <String>
|
Downloads the document in format specified by |
|
url: <String>
|
Downloads image from the url and inserts it to the document. |
|
Label: <String>
|
Shows an in-progress overlay, just like what appears when saving the document, with the given Label. |
|
Hides any in-progress overlay, if present. |
|
|
Mode: 'classic' | 'notebookbar'
|
Changes the user interface: Classic Toolbar or Notebookbar. |
|
Mimetype: <string>
Data: <string>
|
Pastes the data directly to the document bypassing the internal paste mechanism.
Example: |
WOPI editor to host (Response)
MessageId |
Values |
Description |
---|---|---|
|
success: <boolean>
result: <string>
errorMsg: <string>
|
Acknowledgment when load finishes.
|
|
success: <boolean>
result: <string>
errorMsg: <string>
fileName: <string>
|
Acknowledgment when save finishes. This response is only
emitted if
|
|
FollowedViewId: <Number>
IsFollowUser: <Boolean>
IsFollowEditor: <Boolean>
|
Notification about current following state.
If both |
|
Mode: <string>
|
Notification about UI mode switch (Tabbed/Compact)
|
Version Restore
WOPI host to editor
MessageId |
Values |
Description |
---|---|---|
|
Status: <string>
|
The Only possible value is This message is sent by the host before actually restoring the document and after user showed the intent to restore the document. This is so such that if there are any unsaved changes, Online can save them to storage before document is restored. |
Editor to WOPI host
MessageId |
Values |
Description |
---|---|---|
|
Status: <string>
|
This is the reply for the
Possible values for It means that host can go ahead with restoring the document to an earlier revision. |
Note
These messages are only emitted if App_LoadingStatus contains VersionStates in Features. Otherwise, host can immediately restore the version to earlier revision.
Miscellaneous
WOPI host to editor
MessageId |
Values |
Description |
---|---|---|
|
id: <string>
imgurl: <string>
hint: <string>
mobile: <boolean>
label: <string>
insertBefore: <string>
unoCommand: <string>
|
Inserts a button to the top toolbar. It responds
with |
|
id: <string>
|
Hides a button from the toolbar.
|
|
id: <string>
|
Hides a button from the toolbar.
|
|
id: <string>
|
Removes a button from the toolbar.
|
|
id: <string>
|
Removes an element from the status bar. |
|
Hides the menu bar. |
|
|
Shows the menu bar. |
|
|
This restores focus to the application, activating it, and removing any overlay indicating quiescence, and re-connecting to the server if necessary. Useful after leaving the application for a lengthy period, or when wanting to restore browser focus after presenting an overlaid dialog. |
|
|
Hides the horizontal document ruler (Writer only) |
|
|
Shows the horizontal document ruler (Writer only) |
|
|
id: <string>
|
Hides a button from the toolbar.
|
|
id: <string>
|
Shows a button from the toolbar.
|
|
id: <string>
|
Hides an item from the menu.
|
|
id: <string>
|
Shows an item from the menu. id` is the item ID as defined in the browser/src/control/Control.Menubar.js. |
|
action: <string>
action: <string>
disable: <Boolean>
|
Disable the default handler and action for a UI command.
|
|
Command: <string>
Args: <object>
|
Send an UNO command to the editor. See examples in browser/html/framed.doc.html. |
Finding status bar element IDs
Status bar button IDs are defined in the onDocLayerInit
function in
Control.StatusBar.js.
Note that they usually don’t change but there is no guarantee that they
are stable.
Editor to WOPI host
MessageId |
Values |
Description |
---|---|---|
|
id: <string>
|
This event is emitted when the custom button added via |
|
Type: 'print'|'slideshow'|'export'
URL: <string>
|
This event is emitted when the user chooses ‘Print’ or ‘Show slideshow’ or ‘Download As |
|
Requests WOPI host to open a new browser tab and create a new
document. The document type is passed as |
|
|
Requests WOPI host to create appropriate UI, so
that the user can choose path and File
name for creating a copy of the current
file. Response to this query is sent via |
|
|
Notifies WOPI host that the user clicked on the ‘cancel’ option when opening a password protected file, instead of providing the password to decrypt it. |
|
|
Notifies WOPI host that the user clicked a hyperlink
and confirmed they really want to leave the document to
follow the hyperlink. This is especially useful for
integrations that embed Collabora Online into an The integration using this most probably also wants to
trigger the |
|
|
Notification to update the modified status of the document. Values.Modified will be true, if the document has been modified since the last save, otherwise, it will be false if the document has been saved. Note that this notification may be published without a change from the prior value, so care must be taken to check the Values.Modified value and not assume the notification itself implies the modified state of the document on its own. |
Calling Python scripts
WOPI host to editor
MessageId |
Values |
Description |
---|---|---|
|
script. The Values
ScriptFile: <string>
Function: <string>
Values: <object>
|
Calls a Python parameter contains an object with named parameters that are passed to the script. |
Editor to WOPI host
MessageId |
Values |
Description |
---|---|---|
|
commandName: <string>
Values: <object>
|
Returns the result The URL of the script called
|
Mentions
Note
Mentions are only working in Writer for now
Editor to WOPI host
MessageId |
Values |
Description |
---|---|---|
|
type: autocomplete
text: <string>
|
When user starts typing with “@”, CollaboraOnline will send this postMessage with partial text followed by “@” to get the list of usernames from the integrator |
type: selected
username: <string>
|
When user selects the a username from list given by the integrator this message gets fired |
WOPI host to editor
MessageId |
Values |
Description |
---|---|---|
|
list: [{
username: "example-username1",
profile: "link-to-the-profile"
},
{
username: "example-username2",
profile: "link-to-the-profile"
}.....]
|
Based on UI_Mention message of type autocomplete,
integrator should send this message with list of
user object. Each user object contains
|