| OLD | NEW |
|---|
| (Empty) | |
| 1 <h1 class="page_title">Event Pages</h1> |
| 2 <p> |
| 3 Event pages are very similar to |
| 4 <a href="background_pages.html">background pages</a>, |
| 5 with one important difference: |
| 6 event pages are loaded only when they are needed. |
| 7 When the event page is not actively doing something, |
| 8 it is unloaded, freeing memory and other system resources. |
| 9 </p> |
| 10 <h2 id="manifest">Manifest</h2> |
| 11 <p> |
| 12 Register your event page in the |
| 13 <a href="manifest.html">extension manifest</a>: |
| 14 </p> |
| 15 <pre>{ |
| 16 "name": "My extension", |
| 17 ... |
| 18 <b>"background": { |
| 19 "scripts": ["eventPage.js"], |
| 20 "persistent": false |
| 21 }</b>, |
| 22 ... |
| 23 }</pre> |
| 24 <p> |
| 25 Notice that without the "persistent" key, you have |
| 26 a regular background page. Persistence is what differentiates |
| 27 an event page from a background page. |
| 28 </p> |
| 29 <h2 id="lifetime">Lifetime</h2> |
| 30 <p> |
| 31 The event page is loaded when it is "needed", and unloaded |
| 32 when it goes idle again. Here are some examples of things |
| 33 that will cause the event page to load: |
| 34 </p> |
| 35 <ul> |
| 36 <li>The extension is first installed. |
| 37 <li>The event page listens for an event and the event is dispatched. |
| 38 <li>A content script or other extension |
| 39 <a href="messaging.html">sends a message.</a> |
| 40 <li>Another view in the extension (for example, a popup) calls |
| 41 <code><a href="runtime.html#method-getBackgroundPage">chrome.runtime.getBackgrou
ndPage()</a></code>. |
| 42 </ul> |
| 43 <p> |
| 44 Once it has been loaded, the event page will stay running |
| 45 as long as it is active (for example, calling an extension |
| 46 API or issuing a network request). Additionally, the |
| 47 event page will not unload until all visible views (for example, |
| 48 popup windows) are closed. |
| 49 </p> |
| 50 <p> |
| 51 You can observe the lifetime of your event page by clicking |
| 52 on "View Background Pages" in Chrome's Wrench menu, or by |
| 53 opening Chrome's task manager. You can see when your event |
| 54 page loads and unloads by observing when an entry for your |
| 55 extension appears in the list of processes. |
| 56 </p> |
| 57 <p> |
| 58 Once the event page has been idle a short time |
| 59 (a few seconds), the |
| 60 <code><a href="runtime.html#event-onSuspend">chrome.runtime.onSuspend</a></code> |
| 61 event is dispatched. The event page has a few more seconds to handle this |
| 62 event before it is forcibly unloaded. Note that once the event is dispatched, |
| 63 new activity will not keep the event page open. |
| 64 </p> |
| 65 <h2 id="transition">Convert background page to event page</h2> |
| 66 <p> |
| 67 Follow this checklist to convert your extension's |
| 68 (persistent) background page to an event page. |
| 69 <ol> |
| 70 <li>Add <code>"persistent": false</code> to your manifest as shown above. |
| 71 <li>Register to receive any events your extension is interested in |
| 72 each time the event page is loaded. The event page will be loaded once |
| 73 for each new version of your extension. After that it will only be |
| 74 loaded to deliver events you have registered for. |
| 75 <li>If you need to do some initialization when your extension is |
| 76 installed or upgraded, listen to the |
| 77 <code><a href="runtime.html#event-onInstalled">chrome.runtime.onInstalled</a><
/code> |
| 78 event. |
| 79 <li>If you need to keep runtime state in memory throughout a browser |
| 80 session, use the <a href="storage.html">storage API</a> or |
| 81 IndexedDB. Since the event page does not stay loaded for long, you |
| 82 can no longer rely on global variables for runtime state. |
| 83 <li>Listen to the |
| 84 <code><a href="runtime.html#event-onSuspend">chrome.runtime.onSuspend</a></cod
e> |
| 85 event if you need to do last second cleanup before your event page |
| 86 is shut down. However, we recommend persisting periodically instead. |
| 87 That way if your extension crashes without receiving |
| 88 <code>onSuspend</code>, no data will typically be lost. |
| 89 <li>If your extension uses <code>window.setTimeout()</code> or |
| 90 <code>window.setInterval()</code>, switch to using the |
| 91 <a href="alarms.html">alarms API</a> instead. DOM-based timers won't |
| 92 be honored if the event page shuts down. |
| 93 <li>If your extension uses, |
| 94 <code><a href="extension.html#method-getBackgroundPage">chrome.extension.getBa
ckgroundPage()</a></code>, |
| 95 switch to |
| 96 <code><a href="runtime.html#method-getBackgroundPage">chrome.runtime.getBackgr
oundPage()</a></code> |
| 97 instead. The newer method is asynchronous so that it can start the event |
| 98 page if necessary before returning it. |
| 99 <li>If you're using <a href="messaging.html">message passing</a>, be sure |
| 100 to close unused message ports. The event page will not shut down until all |
| 101 message ports are closed. |
| 102 </ol> |
| 103 </p> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10832042:
Extensions Docs Server: Doc conversion script (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src