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 |