Content Process Event Handlers: Difference between revisions

← Older edit

Content Process Event Handlers (view source)

Revision as of 21:01, 29 September 2014

1,083 bytes added , 29 September 2014

no edit summary

Jmathies

Confirmed users

1,983

edits

@@ Line 1: / Line 1: @@
+'''The latest message manager documentation can be found on MDN: [https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/The_message_manager The Message Manager]'''
 [https://bugzilla.mozilla.org/show_bug.cgi?id=542242 Bug 542242] added support for content process event listeners. The basic idea is that chrome asks content process to load script files which add listeners to the content process' root event handling scope. The event listeners can then send messages to chrome process.
-[http://hg.mozilla.org/projects/electrolysis/file/416375517820/content/base/public/nsIFrameMessageManager.idl nsIFrameMessageManager] file has the new interfaces related to content process event listeners and message handling.
+[http://hg.mozilla.org/projects/electrolysis/file/416375517820/content/base/public/nsIFrameMessageManager.idl nsIFrameMessageManager] file has the new interfaces related to content process event listeners and message handling.<br>Note! Currently the API is for JS only.
 ALL THE COMMENTS ABOUT THE API ARE VERY WELCOME! (Ping smaug on IRC)
 <h3>Content Process</h3>
-For each tab the child process has a JS context/scope, which implements nsIContentFrameMessageManager and nsIDOMEventTarget. That scope is above the current top level content window, so capturing event listeners will be called first using event listeners added in that scope and event listeners added to bubble phase will be called after listeners in the content page. The current top level window can be accessed using <b>content</b> property. The scope has also the methods from nsIDOMEventTarget and the new methods from nsIContentFrameMessageManager:
+For each tab the child process has a JS context/scope, which implements nsIContentFrameMessageManager and nsIDOMEventTarget. That scope is above the current top level content window, so capturing event listeners will be called first using event listeners added in that scope and event listeners added to bubble phase will be called after listeners in the content page. The current top level window can be accessed using <b>content</b> property, and <b>docShell</b> points to the nsIDocShell object. The scope has also the methods from nsIDOMEventTarget and the new methods from nsIContentFrameMessageManager:
 - <b>addMessageListener</b> adds a listeners for messages coming from chrome. First parameter is the name of the message, second one is the listener (a JS Function).
@@ Line 14: / Line 18: @@
 - <b>sendAsyncMessage</b> sends asynchronously a message to chrome. It takes 1 or 2 parameters; first one is the name of the message and second one is a JS object which will be JSON'ed.
-- <b>sendSyncMessage</b> sends synchronously a message to chrome. Currently it takes 1 or 2 parameters; first one is the name of the message and second one is a JS object which will be JSON'ed.  If chrome process message listener returns some value, it will be JSON'ed and sendSyncMessage() returns that in an array. (In an array because chrome process may have several listeners for a message and each one may return a result.)<br>
+- <b>sendSyncMessage</b> sends synchronously a message to chrome. Currently it takes 1 or more parameters; first one is the name of the message, second one is a JS object which will be JSON'ed and the rest are JS objects, which chrome process can access from message.objects list.  If chrome process message listener returns some value, it will be JSON'ed and sendSyncMessage() returns that in an array. (In an array because chrome process may have several listeners for a message and each one may return a result.)<br>
 <i>NOTE!</i> In the near future sendSyncMessage() will be able to take more parameters. The parameters after 2nd one will be send as [https://bugzilla.mozilla.org/show_bug.cgi?id=516522 CPOW] objects to the chrome process.
@@ Line 39: / Line 43: @@
    {
      <b>name</b>:    %message name%,
-     <b>sync</b>:    %true or false%.
+    <b>target</b>:  %the target of the message%
-     <b>json</b>:    %json object or null%,
+     <b>sync</b>:    %true or false%,
+     <b>json</b>:    %json object or null%
+    <b>objects</b>: %an array of objects sent using sendSyncMessage% (NOTE, DO NOT USE THIS. .objects will change!)
    }
+<b>target</b> is in chrome the xul:browser element which got the message and on content process side it is the global scope object (aka <b>TabChildGlobal</b>).
 When the CPOW support is added to the synchronous messages, the object will have also property <b>objects</b>.
-When a listener is called, 'this' value points to the target of the message. In content process it is always to root scope. In chrome process it points to the iframe element in which the remote frame is.
+Message listeners can be either Javascript functions, which get message as the
+only parameter, or listeners can be objects which have <b>receiveMessage</b> function as a property.
 <h3>Examples</h3>
-<h4>Forward all the clicks on an HTML A to chrome</h4>
+<h4>Forward all the clicks on HTML A elements to chrome</h4>
 <pre>
 // remote.js
@@ Line 61: / Line 70: @@
      }
    },
-   true);
+   false);
 </pre>
 <pre>
 // some-script-in-chrome.js
+messageManager.loadFrameScript("path://to/remote.js", true);
 messageManager.addMessageListener("linkclick",
    function(m) {
@@ Line 70: / Line 80: @@
    }
 );
+</pre>
+<h4>Forward a message from chrome to content</h4>
+This will broadcast a message to *all* content tabs.
+<pre>
+// contentscript.js
+addMessageListener("MyMessenger.MyMessage", function(obj) {
+  content.wrappedJSObject.console.log("OH HAI");
+});
+</pre>
+<pre>
+// some-script-in-chrome.js
+messageManager.sendAsyncMessage('MyMessenger.MyMessage', {});
 </pre>