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

   1 <h1>Event Pages</h1>
   2
   3
   4 <p>
   5 Event pages are very similar to
   6 <a href="background_pages.html">background pages</a>,
   7 with one important difference:
   8 event pages are loaded only when they are needed.
   9 When the event page is not actively doing something,
  10 it is unloaded, freeing memory and other system resources.
  11 </p>
  12
  13 {{?is_apps}}
  14 <p>
  15 Chrome Apps always use event pages instead of background pages.
  16 It is not possible for a Chrome App to have a persistent background page.
  17 </p>
  18 {{/is_apps}}
  19
  20 <p>
  21 Event pages are available in the stable channel as of Chrome 22, and the
  22 performance advantages are significant, especially on low-power devices. Please
  23 prefer them to persistent background pages whenever possible for new development
  24 and begin <a href="#transition">migrating existing background pages</a> to this
  25 new model.
  26 </p>
  27
  28 <h2 id="manifest">Manifest</h2>
  29
  30 <p>
  31 Register your event page in the
  32 <a href="manifest.html">extension manifest</a>:
  33 </p>
  34
  35 {{^is_apps}}
  36 <pre data-filename="manifest.json">
  37 {
  38   "name": "My extension",
  39   ...
  40   <b>"background": {
  41     "scripts": ["eventPage.js"],
  42     "persistent": false
  43   }</b>,
  44   ...
  45 }
  46 </pre>
  47
  48 <p>
  49 Notice that without the "persistent" key, you have
  50 a regular background page. Persistence is what differentiates
  51 an event page from a background page.
  52 </p>
  53 {{/is_apps}}
  54 {{?is_apps}}
  55 <pre data-filename="manifest.json">
  56 {
  57   "name": "My app",
  58   ...
  59   <b>"background": {
  60     "scripts": ["eventPage.js"]
  61   }</b>,
  62   ...
  63 }
  64 </pre>
  65 {{/is_apps}}
  66
  67 <h2 id="lifetime">Lifetime</h2>
  68
  69 <p>
  70 The event page is loaded when it is "needed", and unloaded
  71 when it goes idle again. Here are some examples of things
  72 that will cause the event page to load:
  73 </p>
  74 <ul>
  75 <li>The app or extension is first installed or is updated to a new version
  76 (in order to <a href="#registration">register for events</a>).
  77 <li>The event page was listening for an event, and the event is dispatched.
  78 <li>A content script or other extension
  79 <a href="messaging.html">sends a message.</a>
  80 <li>Another view in the extension (for example, a popup) calls
  81 <code>$ref:runtime.getBackgroundPage</code>.
  82 </ul>
  83
  84 <p>
  85 Once it has been loaded, the event page will stay running
  86 as long as it is active (for example, calling an extension
  87 API or issuing a network request). Additionally, the
  88 event page will not unload until all visible views (for example,
  89 popup windows) are closed and all message ports are closed. Note
  90 that opening a view does not cause the event page to load, but
  91 only prevents it from closing once loaded.
  92 </p>
  93
  94 <p>
  95 Make sure your event page closes as soon as the event that
  96 opened it is processed.
  97 You can observe the lifetime of your event page by
  98 opening Chrome's task manager. You can see when your event
  99 page loads and unloads by observing when an entry for your
 100 extension appears in the list of processes.
 101 </p>
 102
 103 <p>
 104 Once the event page has been idle a short time
 105 (a few seconds), the
 106 <code>$ref:runtime.onSuspend</code>
 107 event is dispatched. The event page has a few more seconds to handle this
 108 event before it is forcibly unloaded. If during this time an event occurs which
 109 would normally cause the event page to be loaded, the suspend is canceled
 110 and the <code>$ref:runtime.onSuspendCanceled</code> event is dispatched.
 111 </p>
 112
 113 <h2 id="registration">Event registration</h2>
 114
 115 <p>
 116 Chrome keeps track of events that an app or extension has added listeners
 117 for. When it dispatches such an event, the event page is
 118 loaded. Conversely, if the app or extension removes all of its listeners for
 119 an event by calling <code>removeListener</code>, Chrome will no longer
 120 load its event page for that event.
 121 </p>
 122
 123 <p>
 124 Because the listeners themselves only exist in the context of the
 125 event page, you must use <code>addListener</code> each time the event
 126 page loads; only doing so at
 127 <code>$ref:runtime.onInstalled</code>
 128 by itself is insufficient.
 129 </p>
 130
 131 <p>
 132 For an example of event registration in action, you can view the
 133 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/gmail/">Google Mail
 134 Checker</a> extension.
 135 </p>
 136
 137 <h2 id="transition">Convert background page to event page</h2>
 138 <p>
 139 Follow this checklist to convert your extension's
 140 (persistent) background page to an event page.
 141
 142 <ol>
 143   <li>Add <code>"persistent": false</code> to your manifest as shown above.
 144
 145   <li>If your extension uses <code>window.setTimeout()</code> or
 146   <code>window.setInterval()</code>, switch to using the
 147   <a href="alarms.html">alarms API</a> instead. DOM-based timers won't
 148   be honored if the event page shuts down.
 149
 150   <li>Similarly, other asynchronous HTML5 APIs like notifications and
 151   geolocation will not complete if the event page shuts down. Instead,
 152   use equivalent extension APIs, like
 153   <a href="notifications.html">notifications</a>.
 154
 155   <li>If your extension uses,
 156   <code>$ref:extension.getBackgroundPage</code>,
 157   switch to
 158   <code>$ref:runtime.getBackgroundPage</code>
 159   instead. The newer method is asynchronous so that it can start the event
 160   page if necessary before returning it.
 161 </ol>
 162 </p>
 163
 164 <h2 id="best-practices">Best practices when using event pages</h2>
 165 <p>
 166 Keep these tips in mind when using event pages to avoid common subtle pitfalls.
 167
 168 <ol>
 169   <li>Register to receive any events your extension is interested in
 170   each time the event page is loaded. The event page will be loaded once
 171   for each new version of your extension. After that it will only be
 172   loaded to deliver events you have registered for. This generally means that
 173   your event listeners should be added at the top level scope of the event
 174   page, otherwise they may not be available when the event page reloads.
 175
 176   <li>If you need to do some initialization when your extension is
 177   installed or upgraded, listen to the
 178   <code>$ref:runtime.onInstalled</code>
 179   event. This is a good place to register for
 180   <a href="declarativeWebRequest.html">declarativeWebRequest</a> rules,
 181   <a href="contextMenus.html">contextMenu</a> entries, and other such
 182   one-time initialization.
 183
 184   <li>If you need to keep runtime state in memory throughout a browser
 185   session, use the <a href="storage.html">storage API</a> or
 186   IndexedDB. Since the event page does not stay loaded for long, you
 187   can no longer rely on global variables for runtime state.
 188
 189   <li>Use <a href="events.html#filtered">event filters</a> to restrict
 190   your event notifications to the cases you care about. For example, if
 191   you listen to the <code>$ref:tabs.onUpdated</code>
 192   event, try using the
 193   <code>$ref:webNavigation.onCompleted</code>
 194   event with filters instead (the tabs API does not support filters).
 195   That way, your event page will only be loaded for events that
 196   interest you.
 197
 198   <li>Listen to the
 199   <code>$ref:runtime.onSuspend</code>
 200   event if you need to do last second cleanup before your event page
 201   is shut down. However, we recommend persisting periodically instead.
 202   That way if your extension crashes without receiving
 203   <code>onSuspend</code>, no data will typically be lost.
 204
 205   <li>If you're using <a href="messaging.html">message passing</a>, be sure
 206   to close unused message ports. The event page will not shut down until all
 207   message ports are closed.
 208
 209   <li>If you're using the <a href="contextMenus.html">context menus</a> API,
 210   pass a string <code>id</code> parameter to
 211   <code>$ref:contextMenus.create</code>,
 212   and use the
 213   <code>$ref:contextMenus.onClicked</code>
 214   callback instead of an <code>onclick</code> parameter to
 215   <code>$ref:contextMenus.create</code>.
 216
 217   <li>Remember to test that your event page works properly when it is unloaded
 218   and then reloaded, which only happens after several seconds of inactivity.
 219   Common mistakes include doing unnecessary work at page load time (when it
 220   should only be done when the extension is installed); setting an alarm at
 221   page load time (which resets any previous alarm); or not adding event
 222   listeners at page load time.
 223 </ol>
 224 </p>