-
Notifications
You must be signed in to change notification settings - Fork 11
Chrome web data api: v1
DRAFT
The Firefox chrome code and the share web app communicate with each other via postMessage.
The messages passed via postMessage between chrome 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.
Chrome creates a element inside the panel to hold the web app UI and loads the web app. Once that's loaded, it uses browser.contentWindow.wrappedJSObject.addEventListener("message", function (evt) {}) to register a message listener for the web content.
The chrome will only process message events if the event.origin matches the start of the share URL.
Since the chrome 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 chrome will only process a set of whitelisted messages.
See the resource://services-share/panel.js file for the implementation.
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.
Messages passed from the web to the chrome 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 chrome's sharePanel properties.
Messages passed from chrome to the web can be found in the resource://services-share/panel.js file by looking for postMessage.
Data: none
This is called when the web content in the share panel is done loading and ready to receive post message calls from chrome. This is after any javascript initialization during the onload event in the web content.
Data: none
Asks chrome 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.
Data: none
Asks chrome to open the preferences dialog.
Data: none
Hides the panel, but keeps the shareState info for the current tab.
Data: none
Hides the panel, and resets the shareState info for the current tab.
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 chrome, 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.
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.
Data: Object:
- name: String. The preference ID (not including the pref branch prefix)
- value: variable. The value for the pref.
Data: none
Asks chrome 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 chrome 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 chrome for more info on the structure of the shareState data.
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 chrome. See base64Preview message for more information.
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 chrome.
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.
The chrome storage api is meant to mimic localStorage in web content, but using post messaging to pass the data from web content into chrome where it is actually stored. Chrome storage is a key/value storage system. In all api calls for chrome storage, key is a string, value is any javascript object (generally a list or object)
Data: string, the key that is to be fetched
The web content requests a value for key from chrome storage. chrome storage will callback to the web content using webstoreSet below. If the key is not available, the value returned to web content will be NULL.
Data: Object:
- key: string
- value: object
The web content requests a value be stored in chrome storage.
Data: string, the key to be removed
The web content requests a value be deleted in chrome storage.
The web content requests that the entire chrome storage is wiped.
Data: Object:
- key: string
- value: object
storeGetReturn is a callback sent to the web content after the web content has called storeGet
Data: Object:
- key: string
- value: object
Whenever a key value is changed, the chrome notifies content using storeNotifyChange. This includes key removals (in which case value will be null)
When the store has been cleared. Sent as a response to storeRemoveAll.