Extensions Docs Server: Doc conversion script

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

Index: chrome/common/extensions/docs/server2/templates/articles/event_pages.html
diff --git a/chrome/common/extensions/docs/server2/templates/articles/event_pages.html b/chrome/common/extensions/docs/server2/templates/articles/event_pages.html
new file mode 100644
index 0000000000000000000000000000000000000000..45c9c10d579e32ca555eb625e18ecaae53b87832
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/articles/event_pages.html
@@ -0,0 +1,123 @@
+<h1>Event Pages</h1>
+
+
+<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>
+You can observe the lifetime of your event page by clicking
+on "View Background Pages" in Chrome's Wrench menu, or by
+opening Chrome's task manager. You can see when your event
+page loads and unloads by observing when an entry for your
+extension appears in the list of processes.
+</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>
+
+<h2 id="transition">Convert background page to event page</h2>
+<p>
+Follow this checklist to convert your extension's
+(persistent) background page to an event page.
+
+<ol>
+  <li>Add <code>"persistent": false</code> to your manifest as shown above.
+
+  <li>Register to receive any events your extension is interested in
+  each time the event page is loaded. The event page will be loaded once
+  for each new version of your extension. After that it will only be
+  loaded to deliver events you have registered for.
+
+  <li>If you need to do some initialization when your extension is
+  installed or upgraded, listen to the
+  <code><a href="runtime.html#event-onInstalled">chrome.runtime.onInstalled</a></code>
+  event.
+
+  <li>If you need to keep runtime state in memory throughout a browser
+  session, use the <a href="storage.html">storage API</a> or
+  IndexedDB. Since the event page does not stay loaded for long, you
+  can no longer rely on global variables for runtime state.
+
+  <li>Listen to the
+  <code><a href="runtime.html#event-onSuspend">chrome.runtime.onSuspend</a></code>
+  event if you need to do last second cleanup before your event page
+  is shut down. However, we recommend persisting periodically instead.
+  That way if your extension crashes without receiving
+  <code>onSuspend</code>, no data will typically be lost.
+
+  <li>If your extension uses <code>window.setTimeout()</code> or
+  <code>window.setInterval()</code>, switch to using the
+  <a href="alarms.html">alarms API</a> instead. DOM-based timers won't
+  be honored if the event page shuts down.
+
+  <li>If your extension uses,
+  <code><a href="extension.html#method-getBackgroundPage">chrome.extension.getBackgroundPage()</a></code>,
+  switch to
+  <code><a href="runtime.html#method-getBackgroundPage">chrome.runtime.getBackgroundPage()</a></code>
+  instead. The newer method is asynchronous so that it can start the event
+  page if necessary before returning it.
+
+  <li>If you're using <a href="messaging.html">message passing</a>, be sure
+  to close unused message ports. The event page will not shut down until all
+  message ports are closed.
+</ol>
+</p>