Skip to content
This repository has been archived by the owner on Jan 19, 2022. It is now read-only.

Chrome Web Data API: v0

Jump to bottom
philikon edited this page Mar 31, 2011 · 1 revision

The share addon and share web app communicate with each other via postMessage.

Currently (as of March 3/18/2011), the addon initializes the web app by changing the URL of the browser element that contains the web app. It uses a fragment ID (the #part of an URL) to communicate the page options to the web app. The page options are send in the fragment ID as "#options=[encodeURIComponent(JSON.stringify(options))]. The web app then uses JSON.parse() on the options= value to create an object and use it to initialize the page contents: display of the share thumbnail, the URL and description of the page being shared.

However, that fragment ID communication will be converted to the postMessage API in v1 of the data API, see Action Items at the end.

Message Structure

The messages passed via postMessage between the addon and web are JSON messages with the following properties:

  • topic: string with the message topic name.
  • data: JS Object that contains the data relevant to the topic.

So a topic publication can only have one item of data passed to it. However, that data can be an object with an arbitrary set of named properties, or it could be an array, string, any valid JSON value.

Initialization

Addon

The Addon creates a element inside the panel to hold the web app UI. The addon observes "content-document-global-created", and when the observer fires, the addon tests the event to see if it was for the URL that matches the share web app URL.

If the URL matches, then browser.contentWindow.wrappedJSObject.addEventListener("message", function (evt) {}) to register a message listener for the web content.

The Addon will only process message events if the event.origin matches the start of the share URL.

Since the addon is listening to any message event in the web app, and the web app uses postMessage to communicate amongst its JS modules and windows (like the OAUTH window), the addon will only process messages where the topic matches a property name on the sharePanel object. However, there are some properties on sharePanel that it does not make sense for the web app to be able to call, so in v1 of the API, a white list of allowed topic messages should be used.

See the addon's panel.js file for the implementation.

Web

The web app loads the "dispatch" module from scripts/dispatch.js, and calls dispatch.sub() to listen to specific messages. dispatch attaches listeners to postMessage that are unique to each call to dispatch.sub. This is done to avoid errors from any other subscription from stopping code execution flow of other subscriptions.

dispatch.sub will only process message events that come from the exact domain of the page that loaded dispatch, or from "chrome://browser". There is an optional targetOrigin argument to dispatch.sub() that can be passed, which is useful for listening to the OAUTH window results, but the main point is that a message event.origin check is always done.

Message Passing

Messages passed from the web to the addon can be found by looking for dispatch.pub in the web/dev directory. Some of the dispatch.pub messages are used just for web app communication, so the name of the topic in the dispatch.pub needs to be matched against the addon's sharePanel properties.

Messages passed from the addon to the web can be found in the addon's panel.js file by looking for postMessage.

Message From Web

sizeToContent

Data: none

Asks the addon to resize the panel because the web app content size has changed. The panel inspects the size of the web app content and changes the panel size accordingly.

hide

Data: none

Hides the panel, but keeps the shareState info for the current tab.

close

Data: none

Hides the panel, and resets the shareState info for the current tab.

updateStatus

Data: Array, where the following array positions have values:

  • 0: status, a Number. Corresponds to the SHARE_STATE values:
    • 0: SHARE_DONE
    • 1: SHARE_START
    • 2: SHARE_ERROR
  • 1: statusId, a String. An opaque string for the addon, but it represents the DOM ID of the element that has the right status message to show the user, used primarily for errors.
  • 2: message, a String. If an error, this message will be the error message.
  • 3: url, a String. The URL that was shared.

This is probably better converted to an object data value with named arguments for v1, see Action Items at the end.

success

Data: Object:

  • domain: String. The share service domain. Valid values can be found in the web app's scripts/services.js file.
  • username: String. The username of the user on the service domain.
  • userid: String. Some services have an ID that id different from the username.
  • url: String. The URL of the page that was shared. Used for bookmarking.
  • service: The "name" of the service. Used for bookmarking. The value of the name field can be found in the web app's scripts/services.js file.

Sent when the share succeeds. Closes the panel and updates the shareState for that tab.

The domain, username and userid taken together form a unique identifier for which account on which service was used to do the share.

prefChanged

Data: Object:

  • name: String. The preference ID. Just the last dot-part of the preference name. The addon will prepend "extensions." + FFSHARE_EXT_ID + "." to the name before calling Application.prefs.setValue().
  • value: variable. The value for the pref.

getShareState

Data: none

Asks the addon for the current shareState for the page. This is useful for when the web app needs to restore correctly from an error. The panel is usually hidden when the share error occurs, and the user may have changed tabs. So the addon remembers any error state and other info about the page in a shareState variable that is stored per-browser tab. This data is only stored in memory, it is removed on browser window close, or if there is a successful share. See shareState message from the addon for more info on the structure of the shareState data.

generateBase64Preview

Data: String. The image URL to use in generating the preview.

Email-based services can send an image preview of the page by using a base64-based data: URL for an image tag in the email. Sometimes this base64 data is not immediately available because the page being shared has specified an URL to an image that can represent the page. In that case, if the user has configured an email service, this message will be sent to the addon. See base64Preview message for more information.

Messages From Addon

shareState

Data: Object

This message is a response to the getShareState message sent from the web app. It returns the the stored shareState for the current tab. shareState is a JS object that has the following properties:

shareState:

  • options: Object. The JS object representation of the options passed to the web app via the fragment ID.
  • status: Number. One of the SHARE_STATE values. See updateStatus for the values of SHARE_STATE.
  • open: Boolean. Indicates if the panel should be open for the current tab. Not used in the web app, but used by the addon.

base64Preview

Data: String. A data: URL for the base64 preview of a page.

This message is a response to the generateBase64Preview message sent from the web app. It sends a base64 data: URL of a preview of the page, or image that the page specifies as a representation of the page. Only used when sharing a page with an email service, so that a picture can be embedded in the email. It is an async operation to generate the preview, and it is only needed if the user has configured a mail service. Therefore, the creation of the page share options avoids doing this work up front to help speed up the response time for displaying the correct share information.

Action Items

  • [Bug 642658]((https://bugzilla.mozilla.org/show_bug.cgi?id=642658): Convert fragment ID initialization to postMessage (part of v1 of the data API work).
    • Just use the getShareState and shareState for this info? Just have the addon always send shareState on a page change.
  • Bug 643005: The addon should create a whitelist of messages it accepts instead of using a property name check on the sharePanel object, since that object has other private properties which should not be callable from the web app.
  • Bug 643008: Convert updateStatus to use an object with named properties instead of an array.
  • Bug 643010: The addon needs to be sure the addEventListener("message") work is done each time the web app content reloads, which happens occasionally as it tries to update itself. Right now window.addEventListener is used. See if this works across page refreshes, and if so, only do the addEventListener work once.
Clone this wiki locally