Extensions Docs Server: Doc conversion script

chrome/common/extensions/docs/server2/templates/articles/background_pages.html

+<h1>Background Pages</h1>
+
+
+<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.
+Background pages to the rescue.
+</p>
+
+<p>
+As the <a href="overview.html#arch">architecture overview</a> explains,
+the background page is an HTML page that runs in the extension process.
+It exists for the lifetime of your extension,
+and only one instance of it at a time is active.
+</p>
+
+<p>
+In a typical extension with a background page,
+the UI &mdash;
+for example, the browser action or page action
+and any options page &mdash;
+is implemented by dumb views.
+When the view needs some state,
+it requests the state from the background page.
+When the background page notices a state change,
+the background page tells the views to update.
+</p>
+
+<h2 id="manifest">Manifest</h2>
+
+<p>
+Register your background page in the
+<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": {
+    "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>
+
+<p>
+If you need the browser to start up early&mdash;so
+you can display notifications, for example&mdash;then
+you might also want to specify the
+<a href="manifest.html#permissions">"background" permission</a>.
+</p>
+
+
+<h2>Details</h2>
+
+<p>
+You can communicate between your various pages using direct script calls,
+similar to how frames can communicate.
+The <a href="extension.html#method-getViews"><code>chrome.extension.getViews()</code></a> method
+returns a list of window objects
+for every active page belonging to your extension,
+and the
+<a href="extension.html#method-getBackgroundPage"><code>chrome.extension.getBackgroundPage()</code></a> method
+returns the background page.
+</p>
+
+<h2 id="example">Example</h2>
+
+<p>
+The following code snippet demonstrates
+how the background page
+can interact with other pages in the extension.
+It also shows how you can use
+the background page to handle events
+such as user clicks.
+</p>
+
+<p>
+The extension in this example
+has a background page
+and multiple pages created
+(with
+<a href="tabs.html#method-create"><code>chrome.tabs.create()</code></a>)
+from a file named <code>image.html</code>.
+
+</p>
+
+<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 < 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>
+  &lt;script>
+    function setImageUrl(url) {
+      document.getElementById('target').src = url;
+    }
+  &lt;/script>
+
+  &lt;body>
+    &lt;p>
+    Image here:
+    &lt;/p>
+
+    &lt;img id="target" src="white.png" width="640" height="480">
+
+  &lt;/body>
+&lt;/html>
+</pre>