A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on IRC (such as one of these permanent autoconfirmed members).

Difference between revisions of "RemoteDocumentMessaging"

From WHATWG Wiki
Jump to: navigation, search
Line 17: Line 17:
 
The <code>connectTo</code> method opens a message port to a browsing context with name <code>target</code> within the caller's origin (although not necessarily within the caller's unit of related browsing contexts).
 
The <code>connectTo</code> method opens a message port to a browsing context with name <code>target</code> within the caller's origin (although not necessarily within the caller's unit of related browsing contexts).
  
# Create a new MessagePort object owned by the global object of the incumbent script. Let this be the outside port.
+
# Create a new MessagePort object owned by the global object of the incumbent script. Let this be the initiator's port.
# Return the outside port and continue executing the following steps asynchronously.
+
# Return the initiator's port and perform the remaining steps asynchronously.
 +
# Spin the event loop until a browsing context with name <code>target</code> has the same effective script origin as the incumbent script has an active document whose ready state has reached "interactive".  Let this document be the responder's document.
 +
# Create a new MessagePort object owned by the global object of the responder's document. Let this be the responder's port.
 +
# Entangle the initiator's port and the responder's port.
 +
# Create a trusted event that uses the MessageEvent interface, with the name connect, which does not bubble, is not cancelable, has no default action, has a data attribute whose value is initialized to the empty string, has a ports attribute whose value is initialized to a read only array containing only the responder's port, and has a source attribute whose value is initialized to the responder's port, and queue a task to dispatch the event at global object of the responder's document.
  
 
==Examples==
 
==Examples==

Revision as of 18:46, 21 June 2013

Overview

This document describes a proposal for discovering and communicating with "remote" documents. In particular, this proposal lets a web page communicate with another document even if the web page does not have a direct script connection to that document.

Use Cases

The user opens the same word processing document hosted by a document editing web site in two different browser windows. The document editing web site wants to ensure that edits in one window a reflected in the other window without needing to round-trip through the server (e.g., because the user is offline). Unfortunately, the documents are in different units of related browsing contexts, which means the two documents cannot form a direct script connection. Using remote document messaging, the two documents can discover each other and update each other about edits performed by the user.

Specification

partial interface Window {
    MessagePort connectTo(DOMString target);
};

The connectTo method opens a message port to a browsing context with name target within the caller's origin (although not necessarily within the caller's unit of related browsing contexts).

  1. Create a new MessagePort object owned by the global object of the incumbent script. Let this be the initiator's port.
  2. Return the initiator's port and perform the remaining steps asynchronously.
  3. Spin the event loop until a browsing context with name target has the same effective script origin as the incumbent script has an active document whose ready state has reached "interactive". Let this document be the responder's document.
  4. Create a new MessagePort object owned by the global object of the responder's document. Let this be the responder's port.
  5. Entangle the initiator's port and the responder's port.
  6. Create a trusted event that uses the MessageEvent interface, with the name connect, which does not bubble, is not cancelable, has no default action, has a data attribute whose value is initialized to the empty string, has a ports attribute whose value is initialized to a read only array containing only the responder's port, and has a source attribute whose value is initialized to the responder's port, and queue a task to dispatch the event at global object of the responder's document.

Examples

Listener

window.addEventListener("connect", function(message) {
  // message.source is a MessagePort we can use to talk to the remote message, just like in a shared worker.
  var remote = message.source;
  remote.postMessage("Welcome!");
  // You can call remote.addEventListener("message", ... ) to continue communicating with the remote window.
}, false);

// Naming your window makes you discoverable by other documents in your origin.
window.name = "the-listener";

Sender

var port = window.connectTo("the-listener");

port.addEventListener("message", function(message) {
  if (message.data == "Welcome!")
    alert("Success!);
}, false);

port.start();