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