chrome/common/extensions/docs/messaging.html - Issue 10642015: Basic setup for generating app docs

Unified Diff: chrome/common/extensions/docs/messaging.html

Issue 10642015: Basic setup for generating app docs (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src

Patch Set: fix Created 8 years, 6 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

« chrome/common/extensions/docs/js/api_page_generator.js ('K') | « chrome/common/extensions/docs/match_patterns.html ('k') | chrome/common/extensions/docs/notifications.html » ('j') | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')

Index: chrome/common/extensions/docs/messaging.html

diff --git a/chrome/common/extensions/docs/messaging.html b/chrome/common/extensions/docs/messaging.html

deleted file mode 100644

index 20caadf5c1a7f0e80b244c21282a24534f9ab00a..0000000000000000000000000000000000000000

--- a/chrome/common/extensions/docs/messaging.html

+++ /dev/null

@@ -1,497 +0,0 @@

-<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:

- 1) The <head> information in this page is significant, should be uniform

- across api docs and should be edited only with knowledge of the

- templating mechanism.

- 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a

- browser, it will be re-generated from the template, json schema and

- authored overview content.

- 4) The <body>.innerHTML is also generated by an offline step so that this

- page may easily be indexed by search engines.

---><html xmlns="http://www.w3.org/1999/xhtml"><head>

- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

- <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">

- <link href="css/print.css" rel="stylesheet" type="text/css" media="print">

- <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js">

- </script>

- <script type="text/javascript" src="../../../../third_party/json_minify/minify-sans-regexp.js">

- </script>

- <script type="text/javascript" src="js/api_page_generator.js"></script>

- <script type="text/javascript" src="js/bootstrap.js"></script>

- <script type="text/javascript" src="js/sidebar.js"></script>

- <title>Message Passing - Google Chrome Extensions - Google Code</title></head>

- <body> <div id="devModeWarning" class="displayModeWarning">

- You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.

- </div>

- <div id="branchWarning" class="displayModeWarning">

- <span>WARNING: This is the <span id="branchName">BETA</span> documentation.

- It may not work with the stable release of Chrome.</span>

- <select id="branchChooser">

- <option>Choose a different version...

- </option><option value="">Stable

- </option><option value="beta">Beta

- </option><option value="dev">Dev

- </option><option value="trunk">Trunk

- </option></select>

- </div>

- <div id="unofficialWarning" class="displayModeWarning">

- <span>WARNING: This is unofficial documentation. It may not work with the

- current release of Chrome.</span>

- <button id="goToOfficialDocs">Go to the official docs</button>

- </div>

- <div id="gc-container" class="labs">

-

- <!-- In particular, sub-templates that recurse, must be used by allowing

- jstemplate to make a copy of the template in this section which

- are not operated on by way of the jsskip="true" -->

-

- <a id="top"></a>

- <div id="skipto">

- <a href="#gc-pagecontent">Skip to page content</a>

- <a href="#gc-toc">Skip to main navigation</a>

- </div>

-

- <table id="header" width="100%" cellspacing="0" border="0">

- <tbody><tr>

- <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td>

- <td valign="middle" width="100%" style="padding-left:0.6em;">

- <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em">

- <div id="gsc-search-box">

- <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno">

- <input type="hidden" name="ie" value="UTF-8">

- <input type="text" name="q" value="" size="55">

- <input class="gsc-search-button" type="submit" name="sa" value="Search">

- <br>

- <span class="greytext">e.g. "page action" or "tabs"</span>

- </div>

- </form>

- <script type="text/javascript" src="https://www.google.com/jsapi"></script>

- <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>

- <script type="text/javascript" src="https://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script>

- <script type="text/javascript" src="https://www.google.com/coop/cse/brand?form=cse&lang=en"></script>

- </td>

- </tr>

- </tbody></table>

- <div id="codesiteContent" class="">

- <a id="gc-topnav-anchor"></a>

- <div id="gc-topnav">

- <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1>

- <ul id="home" class="gc-topnav-tabs">

- <li id="home_link">

- <a href="index.html" title="Google Chrome Extensions home page">Home</a>

- </li>

- <li id="docs_link">

- <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a>

- </li>

- <li id="faq_link">

- <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a>

- </li>

- <li id="samples_link">

- <a href="samples.html" title="Sample extensions (with source code)">Samples</a>

- </li>

- <li id="group_link">

- <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a>

- </li>

- <li id="so_link">

- <a href="http://stackoverflow.com/questions/tagged/google-chrome-extension" title="[google-chrome-extension] tag on Stack Overflow">Questions?</a>

- </li>

- </ul>

- </div>

- <div class="g-section g-tpl-170">

-

- <div class="g-unit g-first" id="gc-toc">

- <ul>

- <li><a href="getstarted.html">Getting Started</a></li>

- <li><a href="overview.html">Overview</a></li>

- <li><a href="whats_new.html">What's New?</a></li>

- <li><h2><a href="devguide.html">Developer's Guide</a></h2>

- <ul>

- <li>Browser UI

- <ul>

- <li><a href="browserAction.html">Browser Actions</a></li>

- <li><a href="contextMenus.html">Context Menus</a></li>

- <li><a href="notifications.html">Desktop Notifications</a></li>

- <li><a href="omnibox.html">Omnibox</a></li>

- <li><a href="options.html">Options Pages</a></li>

- <li><a href="override.html">Override Pages</a></li>

- <li><a href="pageAction.html">Page Actions</a></li>

- </ul>

- </li>

- <li>Browser Interaction

- <ul>

- <li><a href="bookmarks.html">Bookmarks</a></li>

- <li><a href="cookies.html">Cookies</a></li>

- <li><a href="devtools.html">Developer Tools</a></li>

- <li><a href="events.html">Events</a></li>

- <li><a href="history.html">History</a></li>

- <li><a href="management.html">Management</a></li>

- <li><a href="tabs.html">Tabs</a></li>

- <li><a href="windows.html">Windows</a></li>

- </ul>

- </li>

- <li>Implementation

- <ul>

- <li><a href="a11y.html">Accessibility</a></li>

- <li><a href="background_pages.html">Background Pages</a></li>

- <li><a href="content_scripts.html">Content Scripts</a></li>

- <li><a href="xhr.html">Cross-Origin XHR</a></li>

- <li><a href="i18n.html">Internationalization</a></li>

- <li class="leftNavSelected">Message Passing</li>

- <li><a href="permissions.html">Optional Permissions</a></li>

- <li><a href="npapi.html">NPAPI Plugins</a></li>

- </ul>

- </li>

- <li>Finishing

- <ul>

- <li><a href="hosting.html">Hosting</a></li>

- <li><a href="external_extensions.html">Other Deployment Options</a></li>

- </ul>

- </li>

- </ul>

- </li>

- <li><h2><a href="apps.html">Packaged Apps</a></h2></li>

- <li><h2><a href="tutorials.html">Tutorials</a></h2>

- <ul>

- <li><a href="tut_debugging.html">Debugging</a></li>

- <li><a href="tut_analytics.html">Google Analytics</a></li>

- <li><a href="tut_oauth.html">OAuth</a></li>

- </ul>

- </li>

- <li><h2>Reference</h2>

- <ul>

- <li>Formats

- <ul>

- <li><a href="manifest.html">Manifest Files</a></li>

- <li><a href="match_patterns.html">Match Patterns</a></li>

- </ul>

- </li>

- <li><a href="permission_warnings.html">Permission Warnings</a></li>

- <li><a href="api_index.html">chrome.* APIs</a></li>

- <li><a href="api_other.html">Other APIs</a></li>

- </ul>

- </li>

- <li><h2><a href="samples.html">Samples</a></h2></li>

- <div class="line"> </div>

- <li><h2>More</h2>

- <ul>

- <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li>

- <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li>

- <li><a href="themes.html">Themes</a></li>

- </ul>

- </li>

- </ul>

- </div>

- <script>

- initToggles();

- </script>

- <div class="g-unit" id="gc-pagecontent">

- <div id="pageTitle">

- <h1 class="page_title">Message Passing</h1>

- </div>

-

- <div id="toc">

- <h2>Contents</h2>

- <ol>

- <li>

- <a href="#simple">Simple one-time requests</a>

- <ol>

- </ol>

- </li><li>

- <a href="#connect">Long-lived connections</a>

- <ol>

- </ol>

- </li><li>

- <a href="#external">Cross-extension messaging</a>

- <ol>

- </ol>

- </li><li>

- <a href="#security-considerations">Security considerations</a>

- <ol>

- </ol>

- </li><li>

- <a href="#examples">Examples</a>

- <ol>

- </ol>

- </li>

- </ol>

- </div>

-

-

-

- <div id="static"><div id="pageData-name" class="pageData">Message Passing</div>

-<div id="pageData-showTOC" class="pageData">true</div>

-<p>

-Since content scripts run in the context of a web page and not the extension,

-they often need some way of communicating with the rest of the extension. For

-example, an RSS reader extension might use content scripts to detect the

-presence of an RSS feed on a page, then notify the background page in order to

-display a page action icon for that page.

-</p><p>

-Communication between extensions and their content scripts works by using

-message passing. Either side can listen for messages sent from the other end,

-and respond on the same channel. A message can contain any valid JSON object

-(null, boolean, number, string, array, or object). There is a simple API for

-<a href="#simple">one-time requests</a>

-and a more complex API that allows you to have

-<a href="#connect">long-lived connections</a>

-for exchanging multiple messages with a shared context. It is also possible to

-send a message to another extension if you know its ID, which is covered in

-the

-<a href="#external">cross-extension messages</a>

-section.

-</p><h2 id="simple">Simple one-time requests</h2>

-<p>

-If you only need to send a single message to another part of your extension

-(and optionally get a response back), you should use the simplified

-<a href="extension.html#method-sendMessage">chrome.extension.sendMessage()</a>

-or

-<a href="tabs.html#method-sendMessage">chrome.tabs.sendMessage()</a>

-methods. This lets you send a one-time JSON-serializable message from a

-content script to extension, or vice versa, respectively. An optional

-callback parameter allows you handle the response from the other side, if

-there is one.

-</p><p>

-Sending a request from a content script looks like this:

-</p><pre>contentscript.js

-================

-chrome.extension.sendMessage({greeting: "hello"}, function(response) {

- console.log(response.farewell);

-});

-</pre>

-<p>

-Sending a request from the extension to a content script looks very similar,

-except that you need to specify which tab to send it to. This example

-demonstrates sending a message to the content script in the selected tab.

-</p><pre>background.html

-===============

-chrome.tabs.getSelected(null, function(tab) {

- chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {

- console.log(response.farewell);

- });

-});

-</pre>

-<p>

-On the receiving end, you need to set up an

-<a href="extension.html#event-onMessage">chrome.extension.onMessage</a>

-event listener to handle the message. This looks the same from a content

-script or extension page.

-</p><pre>chrome.extension.onMessage.addListener(

- function(request, sender, sendResponse) {

- console.log(sender.tab ?

- "from a content script:" + sender.tab.url :

- "from the extension");

- if (request.greeting == "hello")

- sendResponse({farewell: "goodbye"});

- });

-</pre>

-<p class="note">

-<b>Note:</b> If multiple pages are listening for onMessage events, only the

-first to call sendResponse() for a particular event will succeed in sending the

-response. All other responses to that event will be ignored.

-</p>

-<h2 id="connect">Long-lived connections</h2>

-<p>

-Sometimes it's useful to have a conversation that lasts longer than a single

-request and response. In this case, you can open a long-lived channel from

-your content script to an extension page, or vice versa, using

-<a href="extension.html#method-connect">chrome.extension.connect()</a>

-or

-<a href="tabs.html#method-connect">chrome.tabs.connect()</a> respectively. The

-channel can optionally have a name, allowing you to distinguish between

-different types of connections.

-</p><p>

-One use case might be an automatic form fill extension. The content script

-could open a channel to the extension page for a particular login, and send a

-message to the extension for each input element on the page to request the

-form data to fill in. The shared connection allows the extension to keep

-shared state linking the several messages coming from the content script.

-</p><p>

-When establishing a connection, each end is given a

-<a href="extension.html#type-Port">Port</a>

-object which is used for sending and receiving messages through that

-connection.

-</p><p>

-Here is how you open a channel from a content script, and send and listen for

-messages:

-</p><pre>contentscript.js

-================

-var port = chrome.extension.connect({name: "knockknock"});

-port.postMessage({joke: "Knock knock"});

-port.onMessage.addListener(function(msg) {

- if (msg.question == "Who's there?")

- port.postMessage({answer: "Madame"});

- else if (msg.question == "Madame who?")

- port.postMessage({answer: "Madame... Bovary"});

-});

-</pre>

-<p>

-Sending a request from the extension to a content script looks very similar,

-except that you need to specify which tab to connect to. Simply replace the

-call to connect in the above example with

-<a href="tabs.html#method-connect">chrome.tabs.connect(tabId, {name:

-"knockknock"})</a>.

-</p><p>

-In order to handle incoming connections, you need to set up a

-<a href="extension.html#event-onConnect">chrome.extension.onConnect</a>

-event listener. This looks the same from a content script or an extension

-page. When another part of your extension calls "connect()", this event is

-fired, along with the

-<a href="extension.html#type-Port">Port</a>

-object you can use to send and receive messages through the connection. Here's

-what it looks like to respond to incoming connections:

-</p><pre>chrome.extension.onConnect.addListener(function(port) {

- console.assert(port.name == "knockknock");

- port.onMessage.addListener(function(msg) {

- if (msg.joke == "Knock knock")

- port.postMessage({question: "Who's there?"});

- else if (msg.answer == "Madame")

- port.postMessage({question: "Madame who?"});

- else if (msg.answer == "Madame... Bovary")

- port.postMessage({question: "I don't get it."});

- });

-});

-</pre>

-<p>

-You may want to find out when a connection is closed, for example if you are

-maintaining separate state for each open port. For this you can listen to the

-<a href="extension.html#type-Port">Port.onDisconnect</a>

-event. This event is fired either when the other side of the channel manually

-calls

-<a href="extension.html#type-Port">Port.disconnect()</a>, or when the page

-containing the port is unloaded (for example if the tab is navigated).

-onDisconnect is guaranteed to be fired only once for any given port.

-</p><h2 id="external">Cross-extension messaging</h2>

-<p>

-In addition to sending messages between different components in your

-extension, you can use the messaging API to communicate with other extensions.

-This lets you expose a public API that other extensions can take advantage of.

-</p><p>

-Listening for incoming requests and connections is similar to the internal

-case, except you use the

-<a href="extension.html#event-onMessageExternal">chrome.extension.onMessageExternal</a>

-or

-<a href="extension.html#event-onConnectExternal">chrome.extension.onConnectExternal</a>

-methods. Here's an example of each:

-</p><pre>// For simple requests:

-chrome.extension.onMessageExternal.addListener(

- function(request, sender, sendResponse) {

- if (sender.id == blacklistedExtension)

- return; // don't allow this extension access

- else if (request.getTargetData)

- sendResponse({targetData: targetData});

- else if (request.activateLasers) {

- var success = activateLasers();

- sendResponse({activateLasers: success});

- }

- });

-// For long-lived connections:

-chrome.extension.onConnectExternal.addListener(function(port) {

- port.onMessage.addListener(function(msg) {

- // See other examples for sample onMessage handlers.

- });

-});

-</pre>

-<p>

-Likewise, sending a message to another extension is similar to sending one

-within your extension. The only difference is that you must pass the ID of the

-extension you want to communicate with. For example:

-</p><pre>// The ID of the extension we want to talk to.

-var laserExtensionId = "abcdefghijklmnoabcdefhijklmnoabc";

-// Make a simple request:

-chrome.extension.sendMessage(laserExtensionId, {getTargetData: true},

- function(response) {

- if (targetInRange(response.targetData))

- chrome.extension.sendMessage(laserExtensionId, {activateLasers: true});

- });

-// Start a long-running conversation:

-var port = chrome.extension.connect(laserExtensionId);

-port.postMessage(...);

-</pre>

-<h2 id="security-considerations">Security considerations</h2>

-<p>

-When receiving a message from a content script or another extension, your

-background page should be careful not to fall victim to <a href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site

-scripting</a>. Specifically, avoid using dangerous APIs such as the

-below:

-</p>

-<pre>background.html

-===============

-chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {

- // WARNING! Might be evaluating an evil script!

- var resp = eval("(" + response.farewell + ")");

-});

-background.html

-===============

-chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {

- // WARNING! Might be injecting a malicious script!

- document.getElementById("resp").innerHTML = response.farewell;

-});

-</pre>

-<p>

-Instead, prefer safer APIs that do not run scripts:

-</p>

-<pre>background.html

-===============

-chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {

- // JSON.parse does not evaluate the attacker's scripts.

- var resp = JSON.parse(response.farewell);

-});

-background.html

-===============

-chrome.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {

- // innerText does not let the attacker inject HTML elements.

- document.getElementById("resp").innerText = response.farewell;

-});

-</pre>

-<h2 id="examples">Examples</h2>

-<p>

-You can find simple examples of communication via messages in the

-<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/messaging/">examples/api/messaging</a>

-directory.

-Also see the

-<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/howto/contentscript_xhr">contentscript_xhr</a> example,

-in which a content script and its parent extension exchange messages,

-so that the parent extension can perform

-cross-site requests on behalf of the content script.

-For more examples and for help in viewing the source code, see

-<a href="samples.html">Samples</a>.

-</p>

-</div>

-

-

- </div>

- </div>

- </div>

- <div id="gc-footer" --="">

- <div class="text">

- <p>

- Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>,

- the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons

- Attribution 3.0 License</a>, and code samples are licensed under the

- <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>.

- </p>

- <p>

- </p>

-

-<script src="https://www.google-analytics.com/urchin.js" type="text/javascript"></script>

-<script src="https://www.google-analytics.com/ga.js" type="text/javascript"></script>

-<script type="text/javascript">

- // chrome doc tracking

- try {

- var engdocs = _gat._getTracker("YT-10763712-2");

- engdocs._trackPageview();

- } catch(err) {}

- // code.google.com site-wide tracking

- try {

- _uacct="UA-18071-1";

- _uanchor=1;

- _uff=0;

- urchinTracker();

- }

- catch(e) {/* urchinTracker not available. */}

-</script>

-

- </div>

- </div>

- </div>

-</body></html>