Add a doc for extension event pages.

BUG=120972 TEST=no Review URL: https://chromiumcodereview.appspot.com/10579027 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@143311 0039d316-1c4b-4281-b951-d872f2087c98
author: mpcomplete@chromium.org <mpcomplete@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> 2012-06-21 00:38:56 +0000
committer: mpcomplete@chromium.org <mpcomplete@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98> 2012-06-21 00:38:56 +0000
commit: 7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f (patch)
tree: f2f2565b5a5ab005c60c4c02256fc4ecf3dc017f
parent: a25e59e84dacb13d2aca32dada9b893d306da21d (diff)
download: chromium_src-7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f.zip
chromium_src-7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f.tar.gz
chromium_src-7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f.tar.bz2
5 files changed, 408 insertions, 0 deletions
diff --git a/chrome/common/extensions/docs/background_pages.html b/chrome/common/extensions/docs/background_pages.html
index 763f271..ddc64f3 100644
--- a/chrome/common/extensions/docs/background_pages.html
+++ b/chrome/common/extensions/docs/background_pages.html
@@ -211,6 +211,10 @@
         <!-- STATIC CONTENT PLACEHOLDER -->
         <div id="static"><div id="pageData-name" class="pageData">Background Pages</div>
 <div id="pageData-showTOC" class="pageData">true</div>
+<p id="eventPageWarning" class="warning">
+  <em>Caution:</em> Consider using event pages instead.
+  <a href="event_pages.html">Learn more</a>.
+</p>
 <p>
 A common need for extensions is to have
 a single long-running script to manage some task or state.
diff --git a/chrome/common/extensions/docs/event_pages.html b/chrome/common/extensions/docs/event_pages.html
new file mode 100644
index 0000000..fad587a
--- /dev/null
+++ b/chrome/common/extensions/docs/event_pages.html
@@ -0,0 +1,315 @@
+<!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>Event Pages - 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">
+      <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->
+      <!-- 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" -->
+       <!-- /SUBTEMPLATES -->
+  <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>
+    <!-- API HEADER -->
+    <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&amp;t13n_langs=en"></script>
+          <script type="text/javascript" src="https://www.google.com/coop/cse/brand?form=cse&amp;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> <!-- end gc-topnav -->
+    <div class="g-section g-tpl-170">
+      <!-- SIDENAV -->
+      <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><a href="messaging.html">Message Passing</a></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">Event Pages</h1>
+      </div>
+        <!-- TABLE OF CONTENTS -->
+        <div id="toc">
+          <h2>Contents</h2>
+          <ol>
+            <li>
+              <a href="#manifest">Manifest</a>
+              <ol>
+              </ol>
+            </li><li>
+              <a href="#lifetime">Lifetime</a>
+              <ol>
+              </ol>
+            </li>
+          </ol>
+        </div>
+        <!-- /TABLE OF CONTENTS -->
+        <!-- Standard content lead-in for experimental API pages -->
+        <!-- STATIC CONTENT PLACEHOLDER -->
+        <div id="static"><div id="pageData-name" class="pageData">Event Pages</div>
+<div id="pageData-showTOC" class="pageData">true</div>
+<p class="warning">
+  <!-- Standard content lead-in for APIs that are not yet available on
+  the stable channel. -->
+  <em>Warning:</em> This API is still under development. It is only
+  available for Chrome users on the
+  <span>
+    <strong>dev</strong>
+      <a href="http://www.chromium.org/getting-involved/dev-channel">early
+      release channel</a>.</span>
+</p>
+<p>
+Event pages are very similar to
+<a href="background_pages.html">background pages</a>,
+with one important difference:
+event pages are loaded only when they are needed.
+When the event page is not actively doing something,
+it is unloaded, freeing memory and other system resources.
+</p>
+<h2 id="manifest">Manifest</h2>
+<p>
+Register your event page in the
+<a href="manifest.html">extension manifest</a>:
+</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"background": {
+    "scripts": ["eventPage.js"],
+    "persistent": false
+  }</b>,
+  ...
+}</pre>
+<p>
+Notice that without the "persistent" key, you have
+a regular background page. Persistence is what differentiates
+an event page from a background page.
+</p>
+<h2 id="lifetime">Lifetime</h2>
+<p>
+The event page is loaded when it is "needed", and unloaded
+when it goes idle again. Here are some examples of things
+that will cause the event page to load:
+</p>
+<ul>
+<li>The extension is first installed.
+</li><li>The event page listens for an event and the event is dispatched.
+</li><li>A content script or other extension
+<a href="messaging.html">sends a message.</a>
+</li><li>Another view in the extension (for example, a popup) calls
+<code><a href="runtime.html#method-getBackgroundPage">chrome.runtime.getBackgroundPage()</a></code>.
+</li></ul>
+<p>
+Once it has been loaded, the event page will stay running
+as long as it is active (for example, calling an extension
+API or issuing a network request). Additionally, the
+event page will not unload until all visible views (for example,
+popup windows) are closed.
+</p>
+<p>
+Once the event page has been idle a short time
+(a few seconds), the
+<code><a href="runtime.html#event-onSuspend">chrome.runtime.onSuspend</a></code>
+event is dispatched. The event page has a few more seconds to handle this
+event before it is forcibly unloaded. Note that once the event is dispatched,
+new activity will not keep the event page open.
+</p>
+</div>
+        <!-- API PAGE -->
+         <!-- /apiPage -->
+      </div> <!-- /gc-pagecontent -->
+    </div> <!-- /g-section -->
+  </div> <!-- /codesiteContent -->
+    <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>
+  ©2011 Google
+  </p>
+<!-- begin analytics -->
+<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>
+<!-- end analytics -->
+      </div>
+    </div> <!-- /gc-footer -->
+  </div> <!-- /gc-container -->
+</body></html>
diff --git a/chrome/common/extensions/docs/js/bootstrap.js b/chrome/common/extensions/docs/js/bootstrap.js
index 3686a38..cc68350 100644
--- a/chrome/common/extensions/docs/js/bootstrap.js
+++ b/chrome/common/extensions/docs/js/bootstrap.js
@@ -83,5 +83,11 @@ if (window.location.search == "?regenerate" ||
         location.href = officialURL + this.value + "/";
       };
     }
+
+    if (currentBranch != 'stable' && currentBranch != 'beta') {
+      var warning = document.getElementById('eventPageWarning');
+      if (warning)
+        warning.style.display = 'block';
+    }
   }
 }
diff --git a/chrome/common/extensions/docs/static/background_pages.html b/chrome/common/extensions/docs/static/background_pages.html
index f494016..7fe67e9 100644
--- a/chrome/common/extensions/docs/static/background_pages.html
+++ b/chrome/common/extensions/docs/static/background_pages.html
@@ -1,6 +1,11 @@
 <div id="pageData-name" class="pageData">Background Pages</div>
 <div id="pageData-showTOC" class="pageData">true</div>
 
+<p id="eventPageWarning" class="warning">
+  <em>Caution:</em> Consider using event pages instead.
+  <a href="event_pages.html">Learn more</a>.
+</p>
+
 <p>
 A common need for extensions is to have
 a single long-running script to manage some task or state.
diff --git a/chrome/common/extensions/docs/static/event_pages.html b/chrome/common/extensions/docs/static/event_pages.html
new file mode 100644
index 0000000..b980809
--- /dev/null
+++ b/chrome/common/extensions/docs/static/event_pages.html
@@ -0,0 +1,78 @@
+<div id="pageData-name" class="pageData">Event Pages</div>
+<div id="pageData-showTOC" class="pageData">true</div>
+
+<p class="warning">
+  <!-- Standard content lead-in for APIs that are not yet available on
+  the stable channel. -->
+  <em>Warning:</em> This API is still under development. It is only
+  available for Chrome users on the
+  <span>
+    <strong>dev</strong>
+      <a href="http://www.chromium.org/getting-involved/dev-channel">early
+      release channel</a>.</span>
+</p>
+
+<p>
+Event pages are very similar to
+<a href="background_pages.html">background pages</a>,
+with one important difference:
+event pages are loaded only when they are needed.
+When the event page is not actively doing something,
+it is unloaded, freeing memory and other system resources.
+</p>
+
+<h2 id="manifest">Manifest</h2>
+
+<p>
+Register your event page in the
+<a href="manifest.html">extension manifest</a>:
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"background": {
+    "scripts": ["eventPage.js"],
+    "persistent": false
+  }</b>,
+  ...
+}</pre>
+
+<p>
+Notice that without the "persistent" key, you have
+a regular background page. Persistence is what differentiates
+an event page from a background page.
+</p>
+
+<h2 id="lifetime">Lifetime</h2>
+
+<p>
+The event page is loaded when it is "needed", and unloaded
+when it goes idle again. Here are some examples of things
+that will cause the event page to load:
+</p>
+<ul>
+<li>The extension is first installed.
+<li>The event page listens for an event and the event is dispatched.
+<li>A content script or other extension
+<a href="messaging.html">sends a message.</a>
+<li>Another view in the extension (for example, a popup) calls
+<code><a href="runtime.html#method-getBackgroundPage">chrome.runtime.getBackgroundPage()</a></code>.
+</ul>
+
+<p>
+Once it has been loaded, the event page will stay running
+as long as it is active (for example, calling an extension
+API or issuing a network request). Additionally, the
+event page will not unload until all visible views (for example,
+popup windows) are closed.
+</p>
+
+<p>
+Once the event page has been idle a short time
+(a few seconds), the
+<code><a href="runtime.html#event-onSuspend">chrome.runtime.onSuspend</a></code>
+event is dispatched. The event page has a few more seconds to handle this
+event before it is forcibly unloaded. Note that once the event is dispatched,
+new activity will not keep the event page open.
+</p>
author	mpcomplete@chromium.org <mpcomplete@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98>	2012-06-21 00:38:56 +0000
committer	mpcomplete@chromium.org <mpcomplete@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98>	2012-06-21 00:38:56 +0000
commit	7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f (patch)
tree	f2f2565b5a5ab005c60c4c02256fc4ecf3dc017f
parent	a25e59e84dacb13d2aca32dada9b893d306da21d (diff)
download	chromium_src-7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f.zip chromium_src-7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f.tar.gz chromium_src-7c588dd70fa1fe8a2b02d1f6b2f61b7f306dd15f.tar.bz2