Disable view source for Developer Tools.

[chromium-blink-merge.git] / chrome / common / extensions / docs / templates / articles / event_pages.html

<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>

{{?is_apps}}
<p>
Chrome Apps always use event pages instead of background pages.
It is not possible for a Chrome App to have a persistent background page.
</p>
{{/is_apps}}

<p>
Event pages are available in the stable channel as of Chrome 22, and the
performance advantages are significant, especially on low-power devices. Please
prefer them to persistent background pages whenever possible for new development
and begin <a href="#transition">migrating existing background pages</a> to this
new model.
</p>

<h2 id="manifest">Manifest</h2>

<p>
Register your event page in the
<a href="manifest.html">extension manifest</a>:
</p>

{{^is_apps}}
<pre data-filename="manifest.json">
{
  "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>
{{/is_apps}}
{{?is_apps}}
<pre data-filename="manifest.json">
{
  "name": "My app",
  ...
  <b>"background": {
    "scripts": ["eventPage.js"]
  }</b>,
  ...
}
</pre>
{{/is_apps}}

<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 app or extension is first installed or is updated to a new version
(in order to <a href="#registration">register for events</a>).
<li>The event page was listening 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>$ref:runtime.getBackgroundPage</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 and all message ports are closed. Note
that opening a view does not cause the event page to load, but
only prevents it from closing once loaded.
</p>

<p>
Make sure your event page closes as soon as the event that
opened it is processed.
You can observe the lifetime of your event page 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>$ref:runtime.onSuspend</code>
event is dispatched. The event page has a few more seconds to handle this
event before it is forcibly unloaded. If during this time an event occurs which
would normally cause the event page to be loaded, the suspend is canceled
and the <code>$ref:runtime.onSuspendCanceled</code> event is dispatched.
</p>

<h2 id="registration">Event registration</h2>

<p>
Chrome keeps track of events that an app or extension has added listeners
for. When it dispatches such an event, the event page is
loaded. Conversely, if the app or extension removes all of its listeners for
an event by calling <code>removeListener</code>, Chrome will no longer
load its event page for that event.
</p>

<p>
Because the listeners themselves only exist in the context of the
event page, you must use <code>addListener</code> each time the event
page loads; only doing so at
<code>$ref:runtime.onInstalled</code>
by itself is insufficient.
</p>

<p>
For an example of event registration in action, you can view the
<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/gmail/">Google Mail
Checker</a> extension.
</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>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>Similarly, other asynchronous HTML5 APIs like notifications and
  geolocation will not complete if the event page shuts down. Instead,
  use equivalent extension APIs, like
  <a href="notifications.html">notifications</a>.

  <li>If your extension uses,
  <code>$ref:extension.getBackgroundPage</code>,
  switch to
  <code>$ref:runtime.getBackgroundPage</code>
  instead. The newer method is asynchronous so that it can start the event
  page if necessary before returning it.
</ol>
</p>

<h2 id="best-practices">Best practices when using event pages</h2>
<p>
Keep these tips in mind when using event pages to avoid common subtle pitfalls.

<ol>
  <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. This generally means that
  your event listeners should be added at the top level scope of the event
  page, otherwise they may not be available when the event page reloads.

  <li>If you need to do some initialization when your extension is
  installed or upgraded, listen to the
  <code>$ref:runtime.onInstalled</code>
  event. This is a good place to register for
  <a href="declarativeWebRequest.html">declarativeWebRequest</a> rules,
  <a href="contextMenus.html">contextMenu</a> entries, and other such
  one-time initialization.

  <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>Use <a href="events.html#filtered">event filters</a> to restrict
  your event notifications to the cases you care about. For example, if
  you listen to the <code>$ref:tabs.onUpdated</code>
  event, try using the
  <code>$ref:webNavigation.onCompleted</code>
  event with filters instead (the tabs API does not support filters).
  That way, your event page will only be loaded for events that
  interest you.

  <li>Listen to the
  <code>$ref:runtime.onSuspend</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 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.

  <li>If you're using the <a href="contextMenus.html">context menus</a> API,
  pass a string <code>id</code> parameter to
  <code>$ref:contextMenus.create</code>,
  and use the
  <code>$ref:contextMenus.onClicked</code>
  callback instead of an <code>onclick</code> parameter to
  <code>$ref:contextMenus.create</code>.

  <li>Remember to test that your event page works properly when it is unloaded
  and then reloaded, which only happens after several seconds of inactivity. 
  Common mistakes include doing unnecessary work at page load time (when it
  should only be done when the extension is installed); setting an alarm at
  page load time (which resets any previous alarm); or not adding event
  listeners at page load time.
</ol>
</p>