Skip to main content

PostMessage API

當 WOPI 主機將 OxOffice Online 包在一個框架( iFrame)時,可以使用 PostMessage API 用來於和 OxOffice Online 互動。這對想要完善整合的 WOPI 主機來講,非常有用。

這個 API 主要基於 WOPI 規範,很少擴充或修改。 所有送出的訊息,都採用以下形式:

{
      "MessageId": "<MessageId>",
      "SendTime": "<Timestamp when message is sent>",
      "Values": {
             "<key>": "<value>"
      }
}

SendTime 是瀏覽器的 Date.now() 傳回的時間戳記。從 WOPI 主機發送的 post 訊息也應該使用相同的格式。

需要注意的是,如 WOPI 規範中所提到的,如果尚未收到 Host_PostmessageReady,OxOffice Online 框架將忽略來自 WOPI 主機框架所有訊息。

另外,由於將 OxOffice Online 嵌入 iFrame 中,因此,OxOffice Online 要求 WOPI 主機回應 CheckFileInfo 中的 PostMessageOrigin 屬性,必須指定,否則 OxOffice Online 將不會送出任何訊息。

初始化

編輯器 🡆 WOPI 主機
MessageID Values 說明
App_LoadingStatus
Status: <String>
DocumentLoadedTime: <Timestamp>

Status 值如下:

  • Frame_Ready:OxOffice Online 的框架已經載入,並且顯示了。
  • Document_Loaded:使用者文件已經完全載入,WOPI 主機可以開始使用 PostMessage API。
    DocumentLoadedTime 代表載入文件所花費的時間。
  • Failed:文件載入失敗,WOPI 主機可以顯示 OxOffice Online 框架,向使用者顯示錯誤訊息。
WOPI 主機 🡆 編輯器
MessageID Values 說明
Host_PostmessageReady
通知 OxOffice Online,WOPI 主機已經準備好收送 PostMessage 了。

查詢

WOPI 主機可以透過 PostMessage API 向編輯器查詢資料。所有來自編輯器回應的 MessageID,都會在您所傳遞的 MessageID 後面加上 "_Resp"。

WOPI 主機 🡆 編輯器
MessageID Values 說明
Get_Views
向編輯器查詢,目前正在編輯文件所有使用者資訊。回應會以 MessageID 為 Get_Views_Resp 的格式傳回。
Get_Export_Formats
向編輯器查詢,目前開啟的文件,支援哪些匯出格式。

得到的回應。

編輯器 🡆 WOPI 主機
MessageID Values 說明
Get_Views_Resp
[
  {
    ViewId: <Number>
	UserId: <String>
	UserName: <String>
	Color: <Number>
	ReadOnly: <Boolean>
	IsCurrentView: <Boolean>
  },...
]
使用 Get_Views 查詢,所得到的所有使用者詳細資訊。
Get_Export_Formats_Resp
[
  {
    Label: <String>
	Format: <String>
  },...
]

使用 Get_Export_Formats 查詢,所得到的回應。

  • Label 是解釋該格式的本地語系內容。
  • Format 是該格式的副檔名。

編輯者管理

WOPI 主機 🡆 編輯器
MessageID Values 說明
Action_RemoveView
ViewId: <Number>
移除指定 Id 的編編者,也就是將某位編輯者踢出共編行列。
編輯器 🡆 WOPI 主機
MessageID Values 說明
Views_List Get_Views_Resp 相同。

所有正在參與該文件編輯的使用者詳細資訊。每次有編輯者加入或離開都會觸發此資訊。

Actions

WOPI 主機 🡆 編輯器

MessageId

Values

Description

Action_Save

DontTerminateEdit: <boolean>
DontSaveIfUnmodified: <boolean>
Notify: <boolean>
ExtendedData: <String>

儲存文件。

  • DontTerminateEdit 和試算表相關,這會中斷編輯模式(文字游標消失)。設為 true 的話,就能儲存檔案,而不會終止編輯模式,也不會中斷使用者編輯試算表。
  • DontSaveIfUnmodified 如果文件內容沒有變更(只是移動了游標),這會阻止 OxOffice Online 把檔案回存雲端硬碟, 如此可防止不必要的版本修訂。
  • Notify 設為 true 時,會在文件儲存完後,通知 WOPI 主機。詳情請參考 Action_Save_Resp
  • ExtendedData 如果標頭X-LOOL-WOPI-ExtendedData 有資料,則會原封不動地傳給WOPI 主機。
    資料內容不可是空白、換行或其他不可列印字元。
    OxOffice Online 可以傳遞多個值,然後 WOPI 主機可以進一步對處理這些值。

Action_SaveAs

Filename: <String>
Notify: <boolean>

建立文件副本,並給予新檔名(另存新檔)。

  • Filename 新文件檔名。
  • Notify 設為 true 時,會在文件儲存完後,通知 WOPI 主機。詳情請參考 Action_Save_Resp

Action_FollowUser

Follow: <Boolean>
ViewId: <Number>

開啟或關閉跟隨特定編輯者功能。

  • Follow true 開啟/ false 關閉。
  • ViewId 要跟隨的編輯者 ID。

Action_Close


關閉文件。

Action_Print


列印文件。

Action_Export

Format: <String>

以 Format 指定的格式下載文件。格式只能是 Get_Export_Formats 所指定列表其中之一。

Action_InsertGraphics

url: <String>

從指定的位址下載圖片並插入文件中。

Action_ShowBusy

Label: <String>

顯示具有 Lable 文字的忙碌畫面,類似存檔中的畫面。

Action_HideBusy


如果有忙碌畫面的話,關掉忙碌畫面。

Action_ChangeUIMode

Mode:'classic' 或 'notebookbar'

變更使用者介面:

  • classic:傳統下拉選單+工具列。
  • notebookbar:分頁式介面。

Action_Paste

Mimetype: <string>
Data: <string>

繞過內部貼上機制,直接貼上資料到文件內。

例如:

Values: {Mimetype: "text/plain;charset=utf-8", Data: "haha"}};

編輯器 🡆 WOPI 主機(回應)

MessageId

Values

Description

Action_Load_Resp

success: <boolean>
result:  <string>
errorMsg: <string>

Acknowledgment when load finishes. success tells if COOL was able to load the document successfully.

result contains the reason the document was not loaded.

errorMsg contains a detailed error message in case loading failed. Probably it will contain the error message returned from the WOPI host.

Action_Save_Resp

success: <boolean>
result: <string>
errorMsg: <string>
fileName: <string>

Acknowledgment when save finishes. This response is only emitted if Notify parameter is mentioned by Action_Save PostMessage API.

success tells if COOL was able to save the document successfully.

result contains the reason the document was not saved. In case, document was not saved because it was not modified, then this parameter contains the string ‘unmodified’. In this case, WOPI hosts can be sure that there are no changes pending in the document to be saved to the storage.

errorMsg contains a detailed error message in case saving failed. Probably it will contain the error message returned from the WOPI host.

fileName if success equals true then contains saved file name.

FollowUser_Changed

FollowedViewId: <Number>
IsFollowUser: <Boolean>
IsFollowEditor: <Boolean>

Notification about current following state.

FollowedViewId tells which user is followed.

IsFollowUser determines if following the specific user is activated.

IsFollowEditor determines if following the editor is activated.

If both IsFollowUser and IsFollowEditor are false then following is inactive.

Action_ChangeUIMode_Resp

Mode: <string>

Notification about UI mode switch (Tabbed/Compact)

Mode tells which mode will be used.

Version Restore

WOPI host to editor

MessageId

Values

Description

Host_VersionRestore

Status: <string>

The Only possible value is Pre_Restore.

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

App_VersionRestore

Status: <string>

This is the reply for the Host_VersionRestore message.

Possible values for Status (for now) is: Pre_Restore_Ack.

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

Insert_Button

id: <string>
imgurl: <string>


hint: <string>

accessKey: <string>

mobile: <boolean>
tablet: <boolean>

label: <string>


insertBefore: <string>


unoCommand: <string>

Inserts a button to the top toolbar. It responds with Clicked_Button post message event on which hosts can react accordingly (except when the unoCommand id parameter is a unique id of the toolbar button. It is recommended to prefix such ids given here given here with some host namespace so that it doesn’t conflict with existing toolbar IDs. In case of conflict, button is not added. imgurl parameter is the link to the image that will be set as button image in the toolbar. The ideal size of the image is 24x24px. The image must be hosted on the host URL to not violate Content-Security-Policyhint This is used as a tooltip of the button.

This is used by acceleratore definitions class. Users can press alt or alt+shift and use this key. One should be careful to not introduce conflicting access keys. mobile whether the button should be shown when the interface switches to mobile mode. tablet whether the button should be shown in tablet mode (true if absent)

label When a read-only document is opened, we don’t have the toolbar at all. In this case, this newly added button is present in file menubar. The text against this label is used as text of the menubar item.

insertBefore Specify the position where the button should be inserted. insertBefore is the button ID (see Finding toolbar button IDs).

unoCommand UNO Command to be executed on button click (Reference). When this property is set, no ‘Clicked_Button’ response is sent. The button click will be handled by LibreOffice.

Hide_Button

id: <string>

Hides a button from the toolbar.

id is the button ID (see Finding toolbar button IDs).

Show_Button

id: <string>

Hides a button from the toolbar.

id is the button ID (see Finding toolbar button IDs).

Remove_Button

id: <string>

Removes a button from the toolbar.

id is the button ID (see Finding toolbar button IDs).

Remove_Statusbar_Element

id: <string>

Removes an element from the status bar. id is the element ID (see Finding status bar element IDs).

Hide_Menubar


Hides the menu bar.

Show_Menubar


Shows the menu bar.

Grab_Focus


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.

Hide_Ruler


Hides the horizontal document ruler (Writer only)

Show_Ruler


Shows the horizontal document ruler (Writer only)

Hide_Menu_Item

id: <string>

Hides an item from the menu.

id is the item ID as defined in the browser/src/control/Control.Menubar.js.

Show_Menu_Item

id: <string>

Shows an item from the menu.

id` is the item ID as defined in the browser/src/control/Control.Menubar.js.

Disable_Default_UIAction

action: <string>
action: <string>
disable: <Boolean>

Disable the default handler and action for a UI command.

action is the action name to enable/disable the default action for. disable controls whether to disable (true) or enable (false) the default action. When set to true, the given UI command will only issue a postMessage without invoking the default action, leaving it up to the client to intercept the postMessage event and handle as necessary. Notice that some actions do not have any default handler to begin with (such as UI_SaveAs and UI_Share) and therefore this will have no effect on them; they only issue postMessage notification anyway without taking any action beyond that. For example, UI_Save will be issued for invoking the save command (from the menu, toolbar, or keyboard shortcut) and no action will take place if ‘UI_Save’ is disabled via the Disable_Default_UIAction ``ommand. Clients who disable ``UI_Save  `` should then issue ``Action_Save themselves, when and if they desire to save the document. Similarly, when disabling UI_Close, the document will not close upon invoking the UI_Close action, instead a postMessage notification will be issued and it will be up to the client to issue Action_Close when they desire. Clients must be careful not to issue duplicate actions when the default handler is enabled, instead, they should only issue actions themselves when the default is disabled. Note: currently only UI_Save and UI_Close are supported.

Send_UNO_Command

Command: <string>
Args: <object>

Send an UNO command to the editor.

See examples in browser/html/framed.doc.html.

Finding toolbar button IDs

Toolbar button IDs are defined in getToolItems/create functions in:

Note that they usually don’t change but there is no guarantee that they are stable.

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

Clicked_Button

id: <string>

This event is emitted when the custom button added

via Insert_Button API above is clicked.

Download_As

Type: 'print'|'slideshow'|'export'
URL: <string>

This event is emitted when the user chooses ‘Print’

or ‘Show slideshow’ or ‘Download As [some type'] and the integration indicates via DownloadAsPostMessage in the CheckFileInfo that it wants to handle the downloading of pdf for printing or svg for slideshows or exported document. This is in situations when the integration cannot rely on browser’s support for downloading like in mobile apps that use the Online in a Web View.

UI_CreateFile


Requests WOPI host to open a new browser tab and create a new document. The document type is passed as DocumentType argument, and can be ‘text’,’spreadsheet’,’presentation’ or ‘drawing’.

UI_SaveAs

Args: {format: '<extension>' }

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 Action_SaveAs message.

Optional arguments: file extension. When this parameter is passed a dropdown appears and the newly saved file is loaded in the integration instead of downloaded.

UI_Cancel_Password


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.

UI_Hyperlink


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 iframe in a mobile app, where actually trying to open a new window should trigger starting a new Activity on Android (or something similar on iOS).

The integration using this most probably also wants to trigger the Disable_Default_UIAction for UI_Hyperlink.

Doc_ModifiedStatus


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

CallPythonScript

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

CallPythonScript-Result

commandName: <string>
Values: <object>

Returns the result The URL of the script called

is in the commandName parameter.

Mentions

Note

Mentions are only working in Writer for now

Editor to WOPI host

MessageId

Values

Description

UI_Mention

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

Action_Mention

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 username and profile