Updated docs for content script messaging.

BUG=no
TEST=no

Review URL: http://codereview.chromium.org/179072

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@25117 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 57 insertions, 4 deletions

diff --git a/chrome/common/extensions/docs/static/content_scripts.html b/chrome/common/extensions/docs/static/content_scripts.html
index 84572e5..52e3558 100644
--- a/chrome/common/extensions/docs/static/content_scripts.html
+++ b/chrome/common/extensions/docs/static/content_scripts.html
@@ -101,13 +101,66 @@ document.getElementById("button").onclick = function() {
 
 <h2 id="messaging">Messaging</h2>
 
-<p>Content scripts can communicate with their parent extension using message passing. The content script opens a channel to the extension using the <a href="extension.html#connect">chrome.extension.connect()</a> method and then sends messages back and forth to it. The messages can contain any valid JSON object (null, boolean, number, string, array, or object).
+<p>Content scripts can communicate with their parent extension using message passing. A message channel can be opened by either the content script or an extension page. Each side of the channel has a <a href="extension.html#port">Port</a> object which can be used to send messages to the other side. The messages can contain any valid JSON object (null, boolean, number, string, array, or object).
 
-<p>The parent extension can also open a channel to a content script in a given tab by calling <a href="tabs.html#connect">chrome.tabs.connect(tabId)</a>.
+<p>The content script opens a channel to the extension using the <a href="extension.html#connect">chrome.extension.connect()</a> method. The parent extension can also open a channel to a content script in a given tab by calling <a href="tabs.html#connect">chrome.tabs.connect(tabId)</a>. In either case, the <a href="extension.html#onConnect">onConnect</a> event is fired in the targeted page(s), and a connection is established.
 
-<p>When a channel is opened from a content script to an extension, the <a href="extension.html#onConnect">onConnect</a> event is fired in all views in the extension. Any view can receive the event. The event contains a <a href="extension.html#port">Port</a> object, which can be used by the extension view to communicate back to the content script.
+<p>When a channel is opened from a content script to an extension, the event is
+fired in all views in the extension. Any view can receive the event.
 
-<p class="comment">[TODO: Complete this]</p>
+<p>For example, suppose you want to write a simple login manager. You want a toolstrip button that lights up when a content script detects a "login" element in a page, and fills in the login info when you press the button.
+
+<p>Your content script would look like this:
+
+<pre>
+contentscript.js
+================
+var e = document.getElementById("login");
+
+// Create a short-lived named channel to the extension and send a single
+// message through it.
+var port = chrome.extension.connect({name: "notifyChannel"});
+port.postMessage({found: (e != undefined)});
+
+// Also listen for new channels from the extension for when the button is
+// pressed.
+chrome.extension.onConnect.addListener(function(port, name) {
+  console.assert(name == "buttonClickedChannel");
+  port.onMessage.addListener(function(msg) {
+    if (msg.buttonClicked) {
+      e.value = msg.passwordValue;
+    }
+  });
+});
+</pre>
+
+<p>with a toolstrip that looks like:
+
+<pre>
+toolstrip.html
+==============
+&lt;div class="toolstrip-button" id="btn" onclick="onClick()"&gt;
+  Fill Password
+&lt;/div&gt;
+&lt;script&gt;
+// Listen for notifications from the content script.
+chrome.extension.onConnect.addListener(function(port, name) {
+  console.assert(name == "notifyChannel");
+  port.onMessage.addListener(function(msg) {
+    // Color our button based on whether a login element was found.
+    var color = msg.found ? "blue" : "grey";
+    document.getElementById("btn").style.backgroundColor = color;
+  });
+});
+function onClick() {
+  // Send our password to the current tab when clicked.
+  chrome.tabs.getSelected(null, function(tab) {
+    var port = chrome.tabs.connect(tab.id, {name: "buttonClickedChannel"});
+    port.postMessage({buttonClicked: true});
+  });
+}
+&lt;/script&gt;
+</pre>
 
 <h2 id="hostPageCommuncation">Communication with the embedding page</h2>