| OLD | NEW |
| 1 <h1>Event Pages</h1> | 1 <h1>Event Pages</h1> |
| 2 | 2 |
| 3 | 3 |
| 4 <p> | 4 <p> |
| 5 Event pages are very similar to | 5 Event pages are very similar to |
| 6 <a href="background_pages.html">background pages</a>, | 6 <a href="background_pages">background pages</a>, |
| 7 with one important difference: | 7 with one important difference: |
| 8 event pages are loaded only when they are needed. | 8 event pages are loaded only when they are needed. |
| 9 When the event page is not actively doing something, | 9 When the event page is not actively doing something, |
| 10 it is unloaded, freeing memory and other system resources. | 10 it is unloaded, freeing memory and other system resources. |
| 11 </p> | 11 </p> |
| 12 | 12 |
| 13 {{?is_apps}} | 13 {{?is_apps}} |
| 14 <p> | 14 <p> |
| 15 Chrome Apps always use event pages instead of background pages. | 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. | 16 It is not possible for a Chrome App to have a persistent background page. |
| 17 </p> | 17 </p> |
| 18 {{/is_apps}} | 18 {{/is_apps}} |
| 19 | 19 |
| 20 <p> | 20 <p> |
| 21 Event pages are available in the stable channel as of Chrome 22, and the | 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 | 22 performance advantages are significant, especially on low-power devices. Please |
| 23 prefer them to persistent background pages whenever possible for new development | 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 | 24 and begin <a href="#transition">migrating existing background pages</a> to this |
| 25 new model. | 25 new model. |
| 26 </p> | 26 </p> |
| 27 | 27 |
| 28 <h2 id="manifest">Manifest</h2> | 28 <h2 id="manifest">Manifest</h2> |
| 29 | 29 |
| 30 <p> | 30 <p> |
| 31 Register your event page in the | 31 Register your event page in the |
| 32 <a href="manifest.html">extension manifest</a>: | 32 <a href="manifest">extension manifest</a>: |
| 33 </p> | 33 </p> |
| 34 | 34 |
| 35 {{^is_apps}} | 35 {{^is_apps}} |
| 36 <pre data-filename="manifest.json"> | 36 <pre data-filename="manifest.json"> |
| 37 { | 37 { |
| 38 "name": "My extension", | 38 "name": "My extension", |
| 39 ... | 39 ... |
| 40 <b>"background": { | 40 <b>"background": { |
| 41 "scripts": ["eventPage.js"], | 41 "scripts": ["eventPage.js"], |
| 42 "persistent": false | 42 "persistent": false |
| (...skipping 28 matching lines...) Expand all Loading... |
| 71 <p> | 71 <p> |
| 72 The event page is loaded when it is "needed", and unloaded | 72 The event page is loaded when it is "needed", and unloaded |
| 73 when it goes idle again. Here are some examples of things | 73 when it goes idle again. Here are some examples of things |
| 74 that will cause the event page to load: | 74 that will cause the event page to load: |
| 75 </p> | 75 </p> |
| 76 <ul> | 76 <ul> |
| 77 <li>The app or extension is first installed or is updated to a new version | 77 <li>The app or extension is first installed or is updated to a new version |
| 78 (in order to <a href="#registration">register for events</a>). | 78 (in order to <a href="#registration">register for events</a>). |
| 79 <li>The event page was listening for an event, and the event is dispatched. | 79 <li>The event page was listening for an event, and the event is dispatched. |
| 80 <li>A content script or other extension | 80 <li>A content script or other extension |
| 81 <a href="messaging.html">sends a message.</a> | 81 <a href="messaging">sends a message.</a> |
| 82 <li>Another view in the extension (for example, a popup) calls | 82 <li>Another view in the extension (for example, a popup) calls |
| 83 <code>$(ref:runtime.getBackgroundPage)</code>. | 83 <code>$(ref:runtime.getBackgroundPage)</code>. |
| 84 </ul> | 84 </ul> |
| 85 | 85 |
| 86 <p> | 86 <p> |
| 87 Once it has been loaded, the event page will stay running | 87 Once it has been loaded, the event page will stay running |
| 88 as long as it is active (for example, calling an extension | 88 as long as it is active (for example, calling an extension |
| 89 API or issuing a network request). Additionally, the | 89 API or issuing a network request). Additionally, the |
| 90 event page will not unload until all visible views (for example, | 90 event page will not unload until all visible views (for example, |
| 91 popup windows) are closed and all message ports are closed. Note | 91 popup windows) are closed and all message ports are closed. Note |
| (...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 139 <h2 id="transition">Convert background page to event page</h2> | 139 <h2 id="transition">Convert background page to event page</h2> |
| 140 <p> | 140 <p> |
| 141 Follow this checklist to convert your extension's | 141 Follow this checklist to convert your extension's |
| 142 (persistent) background page to an event page. | 142 (persistent) background page to an event page. |
| 143 | 143 |
| 144 <ol> | 144 <ol> |
| 145 <li>Add <code>"persistent": false</code> to your manifest as shown above. | 145 <li>Add <code>"persistent": false</code> to your manifest as shown above. |
| 146 | 146 |
| 147 <li>If your extension uses <code>window.setTimeout()</code> or | 147 <li>If your extension uses <code>window.setTimeout()</code> or |
| 148 <code>window.setInterval()</code>, switch to using the | 148 <code>window.setInterval()</code>, switch to using the |
| 149 <a href="alarms.html">alarms API</a> instead. DOM-based timers won't | 149 <a href="alarms">alarms API</a> instead. DOM-based timers won't |
| 150 be honored if the event page shuts down. | 150 be honored if the event page shuts down. |
| 151 | 151 |
| 152 <li>Similarly, other asynchronous HTML5 APIs like notifications and | 152 <li>Similarly, other asynchronous HTML5 APIs like notifications and |
| 153 geolocation will not complete if the event page shuts down. Instead, | 153 geolocation will not complete if the event page shuts down. Instead, |
| 154 use equivalent extension APIs, like | 154 use equivalent extension APIs, like |
| 155 <a href="notifications.html">notifications</a>. | 155 <a href="notifications">notifications</a>. |
| 156 | 156 |
| 157 <li>If your extension uses, | 157 <li>If your extension uses, |
| 158 <code>$(ref:extension.getBackgroundPage)</code>, | 158 <code>$(ref:extension.getBackgroundPage)</code>, |
| 159 switch to | 159 switch to |
| 160 <code>$(ref:runtime.getBackgroundPage)</code> | 160 <code>$(ref:runtime.getBackgroundPage)</code> |
| 161 instead. The newer method is asynchronous so that it can start the event | 161 instead. The newer method is asynchronous so that it can start the event |
| 162 page if necessary before returning it. | 162 page if necessary before returning it. |
| 163 </ol> | 163 </ol> |
| 164 </p> | 164 </p> |
| 165 | 165 |
| 166 <h2 id="best-practices">Best practices when using event pages</h2> | 166 <h2 id="best-practices">Best practices when using event pages</h2> |
| 167 <p> | 167 <p> |
| 168 Keep these tips in mind when using event pages to avoid common subtle pitfalls. | 168 Keep these tips in mind when using event pages to avoid common subtle pitfalls. |
| 169 | 169 |
| 170 <ol> | 170 <ol> |
| 171 <li>Register to receive any events your extension is interested in | 171 <li>Register to receive any events your extension is interested in |
| 172 each time the event page is loaded. The event page will be loaded once | 172 each time the event page is loaded. The event page will be loaded once |
| 173 for each new version of your extension. After that it will only be | 173 for each new version of your extension. After that it will only be |
| 174 loaded to deliver events you have registered for. This generally means that | 174 loaded to deliver events you have registered for. This generally means that |
| 175 your event listeners should be added at the top level scope of the event | 175 your event listeners should be added at the top level scope of the event |
| 176 page, otherwise they may not be available when the event page reloads. | 176 page, otherwise they may not be available when the event page reloads. |
| 177 | 177 |
| 178 <li>If you need to do some initialization when your extension is | 178 <li>If you need to do some initialization when your extension is |
| 179 installed or upgraded, listen to the | 179 installed or upgraded, listen to the |
| 180 <code>$(ref:runtime.onInstalled)</code> | 180 <code>$(ref:runtime.onInstalled)</code> |
| 181 event. This is a good place to register for | 181 event. This is a good place to register for |
| 182 <a href="declarativeWebRequest.html">declarativeWebRequest</a> rules, | 182 <a href="declarativeWebRequest">declarativeWebRequest</a> rules, |
| 183 <a href="contextMenus.html">contextMenu</a> entries, and other such | 183 <a href="contextMenus">contextMenu</a> entries, and other such |
| 184 one-time initialization. | 184 one-time initialization. |
| 185 | 185 |
| 186 <li>If you need to keep runtime state in memory throughout a browser | 186 <li>If you need to keep runtime state in memory throughout a browser |
| 187 session, use the <a href="storage.html">storage API</a> or | 187 session, use the <a href="storage">storage API</a> or |
| 188 IndexedDB. Since the event page does not stay loaded for long, you | 188 IndexedDB. Since the event page does not stay loaded for long, you |
| 189 can no longer rely on global variables for runtime state. | 189 can no longer rely on global variables for runtime state. |
| 190 | 190 |
| 191 <li>Use <a href="events.html#filtered">event filters</a> to restrict | 191 <li>Use <a href="events#filtered">event filters</a> to restrict |
| 192 your event notifications to the cases you care about. For example, if | 192 your event notifications to the cases you care about. For example, if |
| 193 you listen to the <code>$(ref:tabs.onUpdated)</code> | 193 you listen to the <code>$(ref:tabs.onUpdated)</code> |
| 194 event, try using the | 194 event, try using the |
| 195 <code>$(ref:webNavigation.onCompleted)</code> | 195 <code>$(ref:webNavigation.onCompleted)</code> |
| 196 event with filters instead (the tabs API does not support filters). | 196 event with filters instead (the tabs API does not support filters). |
| 197 That way, your event page will only be loaded for events that | 197 That way, your event page will only be loaded for events that |
| 198 interest you. | 198 interest you. |
| 199 | 199 |
| 200 <li>Listen to the | 200 <li>Listen to the |
| 201 <code>$(ref:runtime.onSuspend)</code> | 201 <code>$(ref:runtime.onSuspend)</code> |
| 202 event if you need to do last second cleanup before your event page | 202 event if you need to do last second cleanup before your event page |
| 203 is shut down. However, we recommend persisting periodically instead. | 203 is shut down. However, we recommend persisting periodically instead. |
| 204 That way if your extension crashes without receiving | 204 That way if your extension crashes without receiving |
| 205 <code>onSuspend</code>, no data will typically be lost. | 205 <code>onSuspend</code>, no data will typically be lost. |
| 206 | 206 |
| 207 <li>If you're using <a href="messaging.html">message passing</a>, be sure | 207 <li>If you're using <a href="messaging">message passing</a>, be sure |
| 208 to close unused message ports. The event page will not shut down until all | 208 to close unused message ports. The event page will not shut down until all |
| 209 message ports are closed. | 209 message ports are closed. |
| 210 | 210 |
| 211 <li>If you're using the <a href="contextMenus.html">context menus</a> API, | 211 <li>If you're using the <a href="contextMenus">context menus</a> API, |
| 212 pass a string <code>id</code> parameter to | 212 pass a string <code>id</code> parameter to |
| 213 <code>$(ref:contextMenus.create)</code>, | 213 <code>$(ref:contextMenus.create)</code>, |
| 214 and use the | 214 and use the |
| 215 <code>$(ref:contextMenus.onClicked)</code> | 215 <code>$(ref:contextMenus.onClicked)</code> |
| 216 callback instead of an <code>onclick</code> parameter to | 216 callback instead of an <code>onclick</code> parameter to |
| 217 <code>$(ref:contextMenus.create)</code>. | 217 <code>$(ref:contextMenus.create)</code>. |
| 218 | 218 |
| 219 <li>Remember to test that your event page works properly when it is unloaded | 219 <li>Remember to test that your event page works properly when it is unloaded |
| 220 and then reloaded, which only happens after several seconds of inactivity. | 220 and then reloaded, which only happens after several seconds of inactivity. |
| 221 Common mistakes include doing unnecessary work at page load time (when it | 221 Common mistakes include doing unnecessary work at page load time (when it |
| 222 should only be done when the extension is installed); setting an alarm at | 222 should only be done when the extension is installed); setting an alarm at |
| 223 page load time (which resets any previous alarm); or not adding event | 223 page load time (which resets any previous alarm); or not adding event |
| 224 listeners at page load time. | 224 listeners at page load time. |
| 225 </ol> | 225 </ol> |
| 226 </p> | 226 </p> |
| OLD | NEW |