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