Web Messaging API

💁 We encourage the customers to use the Query String API, or the JavaScript API if they integrate Spreadsheet Viewer with an app that is implemented in JavaScript or TypeScript. Web Messaging API is a lower-level API that should be used with other languages or native apps.

---

Spreadsheet Viewer is designed to be used in an iframe or a window and be controlled from the outside code. For that, it implements a low-level Web Messaging API (see the MSN docs about postMessage), a cross-document messaging interface defined in the HTML standard.

This API is asynchronous with bidirectional messaging. One direction is referred to as "request messages" (from host to SV), the second direction is referred to as "callback messages" (from SV to host).

Every message is implemented as a postMessage call in which the message is encoded as a JavaScript object. There are two mandatory properties in the object: name and svId. Other properties are used to carry the details of the message.

This low-level API must be used directly when integrating SV with a native app or any other non-JavaScript app.

The below sequence diagram illustrates the main intended correspondence between the request messages, the callback messages and the views (🏗 this is still work in progress):

---

Web Messaging API Reference

Request messages

Request messages are emitted from the parent frame and are listened to in the iframe. They are used to steer the UI of Spreadsheet Viewer from the host app.

Configure

Request message that reconfigures up the internal state of the Spreadsheet Viewer iframe in the runtime.

Properties:

• name: configure
• themeStylesheet: Optional. A string representing the name of the built-in theme (color scheme) which can be either light or dark. Default value: dark
• licenseKey: Optional. A string representing Spreadsheet Viewer license key. Default value: empty string (meaning: unlicensed)

Load a spreadsheet file from a URL or a Data URL

Request message to Spreadsheet Viewer to render a file. Provided a URL, Spreadsheet Viewer will download and render the file. Provided a Data URL, Spreadsheet Viewer will render the file contents without additional downloading. See MDN for guidelines about Data URL: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs.

While loading and parsing the workbook file, Spreadsheet Viewer displays an animated loading screen.

Properties:

• name: loadWorkbook
• workbook: Required. A URL to a workbook file, or a base64-encoded string (Data URL) representing the file contents or an ArrayBuffer with the file contents.
• sheet: Required. A number, starting from 0, representing the index of the sheet within the document that will be open after the file loads.
• fileName: Required if workbook is an ArrayBuffer, otherwise optional. A string representing a file name of the current workbook. If the file name is not provided and workbook is an HTTP(S) URL, the app considers the last segment of the URL as the file name (after the last /). Otherwise, if the file name cannot be determined, the app will show "Unnamed file" as the file name.

Example:

// send message to contentWindow
document.querySelector('iframe#spreadsheet-viewer').contentWindow.postMessage({
  'name': 'loadWorkbook',
  'workbook': url,
  'sheet': sheet
}, '*');

Select cells in the spreadsheet

Request message to Spreadsheet Viewer to select cells in a loaded spreadsheet.

Properties:

• name: selectCells
• range: Required. An array of four numbers. Each number, starting from 0, represents in order: starting row, starting column, ending row, ending column.

document.querySelector('iframe#spreadsheet-viewer').contentWindow.postMessage({
  'name': 'selectCells',
  'range': [0, 0, 1, 1] // select 4 cells: A1, A2, B1, B2
}, '*');

Callback messages

Callback messages are emitted from the iframe and can be listened to in the parent frame. They allow the host app to observe UI interactions (screen changed e.g. name: screenLoaded, screen: crash, button clicked e.g. name: actionPerformed, action: close, ...) performed by the end-user in Spreadsheet Viewer.

Callback messages are emitted also if they are the result of a request message.

Change of the active sheet

The callback from Spreadsheet Viewer emitted when a sheet is changed by the end-user. The message includes the index of the new active sheet.

Properties:

• name: activeSheetChanged
• sheet: a number, starting from 0, representing the index of the sheet within the document

Example:

// get a message from Spreadsheet Viewer iframe
window.addEventListener('message', function(e) {
  if (e.data.name === 'activeSheetChanged') {
    var sheet = e.data.sheet
  }
});

Change of the cells selection

The callback from Spreadsheet Viewer emitted when cells are selected by the end-user. The message includes the range of the selected cells.

Properties:

• name: cellSelectionChanged
• range: an array of four numbers. Each number, starting from 0, represents in order: starting row, starting column, ending row, ending column.

window.addEventListener('message', function(e) {
  if (e.data.name === 'cellSelectionChanged') {
    var range = e.data.range
    console.log(range) // example output of cells A1, A2, B1, B2: [0, 0, 1, 1]
  }
});