Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(542)

Side by Side Diff: chrome/common/extensions/docs/templates/articles/event_pages.html

Issue 219213007: Remove .html extension from links (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Created 6 years, 7 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
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
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
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>
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698