Document the background.scripts feature.

BUG=107791

Review URL: https://chromiumcodereview.appspot.com/9190071

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

10 files changed, 130 insertions, 72 deletions

diff --git a/chrome/common/extensions/docs/background_pages.html b/chrome/common/extensions/docs/background_pages.html
index db0c900..89b31c0 100644
--- a/chrome/common/extensions/docs/background_pages.html
+++ b/chrome/common/extensions/docs/background_pages.html
@@ -373,14 +373,43 @@ the background page tells the views to update.
 
 <p>
 Register your background page in the
-<a href="manifest.html">extension manifest</a>
+<a href="manifest.html">extension manifest</a>.
+In the common case, a background page
+does not require any HTML markup.
+These kind of background pages can be
+implemented using JavaScript files alone,
 like this:
 </p>
 
 <pre>{
   "name": "My extension",
   ...
-  <b>"background_page": "background.html"</b>,
+  <b>"background": {
+    "scripts": ["background.js"]
+  }</b>,
+  ...
+}</pre>
+
+<p>
+A background page will be generated
+by the extension system
+that includes each of the files listed
+in the <code>scripts</code> property.
+</p>
+
+<p>
+If you need to specify HTML
+in your background page, you can
+do that using the <code>page</code>
+property instead:
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"background": {
+    "page": ["background.html"]
+  }</b>,
   ...
 }</pre>
 
@@ -426,31 +455,27 @@ from a file named <code>image.html</code>.
 <!-- [PENDING: Once we have our set of samples, we should point to the example this is from and to other relevant examples.  This is currently untested code derived from the screenshot sample.] -->
 </p>
 
-<pre><em>//In the background page:</em>
-&lt;html&gt;
-  &lt;script&gt;
-    //React when a browser action's icon is clicked.
-    chrome.browserAction.onClicked.addListener(function(tab) {
-      var viewTabUrl = chrome.extension.getURL('image.html');
-      var imageUrl = <em>/* an image's URL */</em>;
-
-      //Look through all the pages in this extension to find one we can use.
-      var views = chrome.extension.getViews();
-      for (var i = 0; i &lt; views.length; i++) {
-        var view = views[i];
-
-        //If this view has the right URL and hasn't been used yet...
-        if (view.location.href == viewTabUrl &amp;&amp; !view.imageAlreadySet) {
-
-          //...call one of its functions and set a property.
-          view.setImageUrl(imageUrl);
-          view.imageAlreadySet = true;
-          break; //we're done
-        }
-      }
-    });
-  &lt;/script&gt;
-&lt;/html&gt;
+<pre><em>//In background.js:</em>
+// React when a browser action's icon is clicked.
+chrome.browserAction.onClicked.addListener(function(tab) {
+  var viewTabUrl = chrome.extension.getURL('image.html');
+  var imageUrl = <em>/* an image's URL */</em>;
+
+  // Look through all the pages in this extension to find one we can use.
+  var views = chrome.extension.getViews();
+  for (var i = 0; i &lt; views.length; i++) {
+    var view = views[i];
+
+    // If this view has the right URL and hasn't been used yet...
+    if (view.location.href == viewTabUrl &amp;&amp; !view.imageAlreadySet) {
+
+      // ...call one of its functions and set a property.
+      view.setImageUrl(imageUrl);
+      view.imageAlreadySet = true;
+      break; // we're done
+    }
+  }
+});
 
 <em>//In image.html:</em>
 &lt;html&gt;
@@ -470,7 +495,6 @@ from a file named <code>image.html</code>.
   &lt;/body&gt;
 &lt;/html&gt;
 </pre>
-
 </div>
 
         <!-- API PAGE -->
diff --git a/chrome/common/extensions/docs/experimental.infobars.html b/chrome/common/extensions/docs/experimental.infobars.html
index 163eefa..b3bc29b 100644
--- a/chrome/common/extensions/docs/experimental.infobars.html
+++ b/chrome/common/extensions/docs/experimental.infobars.html
@@ -402,7 +402,9 @@ For example:
   <b>"icons": {</b>
     <b>"16": "16.png"</b>
   <b>},</b>
-  "background_page": "background.html"
+  "background": {
+    "scripts": ["background.js"]
+  }
 }</pre>
 
 <!-- END AUTHORED CONTENT -->
diff --git a/chrome/common/extensions/docs/manifest.html b/chrome/common/extensions/docs/manifest.html
index 4dbd5fe..308f4c1 100644
--- a/chrome/common/extensions/docs/manifest.html
+++ b/chrome/common/extensions/docs/manifest.html
@@ -401,7 +401,7 @@ are <b>name</b> and <b>version</b>.
   "<a href="#app">app</a>": {...},
 
   <em>// Add any of these that you need</em>
-  "<a href="background_pages.html">background_page</a>": "<em>aFile</em>.html",
+  "<a href="background_pages.html">background</a>": {...},
   "<a href="override.html">chrome_url_overrides</a>": {...},
   "<a href="content_scripts.html">content_scripts</a>": [...],
   "<a href="#content_security_policy">content_security_policy</a>": "<em>policyString</em>",
diff --git a/chrome/common/extensions/docs/omnibox.html b/chrome/common/extensions/docs/omnibox.html
index 212f38a..a0a4a16 100644
--- a/chrome/common/extensions/docs/omnibox.html
+++ b/chrome/common/extensions/docs/omnibox.html
@@ -442,7 +442,9 @@ For example:
   <b>"icons": {</b>
     <b>"16": "16-full-color.png"</b>
   <b>},</b>
-  "background_page": "background.html"
+  "background": {
+    "scripts": ["background.js"]
+  }
 }</pre>
 
 <p class="note">
diff --git a/chrome/common/extensions/docs/overview.html b/chrome/common/extensions/docs/overview.html
index 452e0b0..4c94b20 100644
--- a/chrome/common/extensions/docs/overview.html
+++ b/chrome/common/extensions/docs/overview.html
@@ -601,7 +601,9 @@ that uses information from google.com:
   "version": "2.1",
   "description": "Gets information from Google.",
   "icons": { "128": "icon_128.png" },
-  "background_page": "bg.html",
+  "background": {
+    "scripts": ["bg.js"]
+  },
   "permissions": ["http://*.google.com/", "https://*.google.com/"],
   "browser_action": {
     "default_title": "",
@@ -637,7 +639,7 @@ that has at least two extensions installed:
 a browser action (yellow icon)
 and a page action (blue icon).
 Both the browser action and the page action
-have background pages defined by HTML files.
+have background pages.
 This figure shows the browser action's background page,
 which is defined by <code>background.html</code>
 and has JavaScript code that controls
@@ -668,14 +670,13 @@ Here are some examples of extensions that usually
     presents its UI solely through a popup
     (and perhaps an options page).
   </li>
-  <li> 
+  <li>
     An extension that provides an <em>override page</em>—a
     page that replaces a standard Chrome page.
   </li>
   <li>
     An extension with a content script
-    that doesn't use cross-origin XMLHttpRequests or localStorage,
-    and that doesn't need to use
+    that doesn't use localStorage or
     <a href="#apis">extension APIs</a>.
   </li>
   <li>
diff --git a/chrome/common/extensions/docs/static/background_pages.html b/chrome/common/extensions/docs/static/background_pages.html
index f4689be..d703ea2 100644
--- a/chrome/common/extensions/docs/static/background_pages.html
+++ b/chrome/common/extensions/docs/static/background_pages.html
@@ -30,14 +30,43 @@ the background page tells the views to update.
 
 <p>
 Register your background page in the
-<a href="manifest.html">extension manifest</a>
+<a href="manifest.html">extension manifest</a>.
+In the common case, a background page
+does not require any HTML markup.
+These kind of background pages can be
+implemented using JavaScript files alone,
 like this:
 </p>
 
 <pre>{
   "name": "My extension",
   ...
-  <b>"background_page": "background.html"</b>,
+  <b>"background": {
+    "scripts": ["background.js"]
+  }</b>,
+  ...
+}</pre>
+
+<p>
+A background page will be generated
+by the extension system
+that includes each of the files listed
+in the <code>scripts</code> property.
+</p>
+
+<p>
+If you need to specify HTML
+in your background page, you can
+do that using the <code>page</code>
+property instead:
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"background": {
+    "page": ["background.html"]
+  }</b>,
   ...
 }</pre>
 
@@ -84,31 +113,27 @@ from a file named <code>image.html</code>.
 </p>
 
 <pre>
-<em>//In the background page:</em>
-&lt;html>
-  &lt;script>
-    //React when a browser action's icon is clicked.
-    chrome.browserAction.onClicked.addListener(function(tab) {
-      var viewTabUrl = chrome.extension.getURL('image.html');
-      var imageUrl = <em>/* an image's URL */</em>;
-
-      //Look through all the pages in this extension to find one we can use.
-      var views = chrome.extension.getViews();
-      for (var i = 0; i < views.length; i++) {
-        var view = views[i];
-
-        //If this view has the right URL and hasn't been used yet...
-        if (view.location.href == viewTabUrl && !view.imageAlreadySet) {
-
-          //...call one of its functions and set a property.
-          view.setImageUrl(imageUrl);
-          view.imageAlreadySet = true;
-          break; //we're done
-        }
-      }
-    });
-  &lt;/script>
-&lt;/html>
+<em>//In background.js:</em>
+// React when a browser action's icon is clicked.
+chrome.browserAction.onClicked.addListener(function(tab) {
+  var viewTabUrl = chrome.extension.getURL('image.html');
+  var imageUrl = <em>/* an image's URL */</em>;
+
+  // Look through all the pages in this extension to find one we can use.
+  var views = chrome.extension.getViews();
+  for (var i = 0; i < views.length; i++) {
+    var view = views[i];
+
+    // If this view has the right URL and hasn't been used yet...
+    if (view.location.href == viewTabUrl && !view.imageAlreadySet) {
+
+      // ...call one of its functions and set a property.
+      view.setImageUrl(imageUrl);
+      view.imageAlreadySet = true;
+      break; // we're done
+    }
+  }
+});
 
 <em>//In image.html:</em>
 &lt;html>
@@ -128,4 +153,3 @@ from a file named <code>image.html</code>.
   &lt;/body>
 &lt;/html>
 </pre>
-
diff --git a/chrome/common/extensions/docs/static/experimental.infobars.html b/chrome/common/extensions/docs/static/experimental.infobars.html
index e526091..43b956c 100644
--- a/chrome/common/extensions/docs/static/experimental.infobars.html
+++ b/chrome/common/extensions/docs/static/experimental.infobars.html
@@ -43,7 +43,9 @@ For example:
   <b>"icons": {</b>
     <b>"16": "16.png"</b>
   <b>},</b>
-  "background_page": "background.html"
+  "background": {
+    "scripts": ["background.js"]
+  }
 }</pre>
 
 <!-- END AUTHORED CONTENT -->
diff --git a/chrome/common/extensions/docs/static/manifest.html b/chrome/common/extensions/docs/static/manifest.html
index 2fc6a02..8d7eef7 100644
--- a/chrome/common/extensions/docs/static/manifest.html
+++ b/chrome/common/extensions/docs/static/manifest.html
@@ -36,7 +36,7 @@ are <b>name</b> and <b>version</b>.
   "<a href="#app">app</a>": {...},
 
   <em>// Add any of these that you need</em>
-  "<a href="background_pages.html">background_page</a>": "<em>aFile</em>.html",
+  "<a href="background_pages.html">background</a>": {...},
   "<a href="override.html">chrome_url_overrides</a>": {...},
   "<a href="content_scripts.html">content_scripts</a>": [...],
   "<a href="#content_security_policy">content_security_policy</a>": "<em>policyString</em>",
diff --git a/chrome/common/extensions/docs/static/omnibox.html b/chrome/common/extensions/docs/static/omnibox.html
index 422c9cf5..c71504b 100644
--- a/chrome/common/extensions/docs/static/omnibox.html
+++ b/chrome/common/extensions/docs/static/omnibox.html
@@ -53,7 +53,9 @@ For example:
   <b>"icons": {</b>
     <b>"16": "16-full-color.png"</b>
   <b>},</b>
-  "background_page": "background.html"
+  "background": {
+    "scripts": ["background.js"]
+  }
 }</pre>
 
 <p class="note">
diff --git a/chrome/common/extensions/docs/static/overview.html b/chrome/common/extensions/docs/static/overview.html
index 160091c..6f22946 100644
--- a/chrome/common/extensions/docs/static/overview.html
+++ b/chrome/common/extensions/docs/static/overview.html
@@ -228,7 +228,9 @@ that uses information from google.com:
   "version": "2.1",
   "description": "Gets information from Google.",
   "icons": { "128": "icon_128.png" },
-  "background_page": "bg.html",
+  "background": {
+    "scripts": ["bg.js"]
+  },
   "permissions": ["http://*.google.com/", "https://*.google.com/"],
   "browser_action": {
     "default_title": "",
@@ -264,7 +266,7 @@ that has at least two extensions installed:
 a browser action (yellow icon)
 and a page action (blue icon).
 Both the browser action and the page action
-have background pages defined by HTML files.
+have background pages.
 This figure shows the browser action's background page,
 which is defined by <code>background.html</code>
 and has JavaScript code that controls
@@ -297,14 +299,13 @@ Here are some examples of extensions that usually
     presents its UI solely through a popup
     (and perhaps an options page).
   </li>
-  <li> 
+  <li>
     An extension that provides an <em>override page</em>&mdash;a
     page that replaces a standard Chrome page.
   </li>
   <li>
     An extension with a content script
-    that doesn't use cross-origin XMLHttpRequests or localStorage,
-    and that doesn't need to use
+    that doesn't use localStorage or
     <a href="#apis">extension APIs</a>.
   </li>
   <li>