OLD | NEW |
1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc.
Note: | 1 <!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc.
Note: |
2 1) The <head> information in this page is significant, should be uniform | 2 1) The <head> information in this page is significant, should be uniform |
3 across api docs and should be edited only with knowledge of the | 3 across api docs and should be edited only with knowledge of the |
4 templating mechanism. | 4 templating mechanism. |
5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a | 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a |
6 browser, it will be re-generated from the template, json schema and | 6 browser, it will be re-generated from the template, json schema and |
7 authored overview content. | 7 authored overview content. |
8 4) The <body>.innerHTML is also generated by an offline step so that this | 8 4) The <body>.innerHTML is also generated by an offline step so that this |
9 page may easily be indexed by search engines. | 9 page may easily be indexed by search engines. |
10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> | 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> |
(...skipping 149 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
160 </li><li jsinstance="2"> | 160 </li><li jsinstance="2"> |
161 <a href="#arch">Architecture</a> | 161 <a href="#arch">Architecture</a> |
162 <ol> | 162 <ol> |
163 <li jsinstance="0"> | 163 <li jsinstance="0"> |
164 <a href="#background">The background page</a> | 164 <a href="#background">The background page</a> |
165 </li><li jsinstance="*1"> | 165 </li><li jsinstance="*1"> |
166 <a href="#contentScripts">Content scripts</a> | 166 <a href="#contentScripts">Content scripts</a> |
167 </li> | 167 </li> |
168 </ol> | 168 </ol> |
169 </li><li jsinstance="3"> | 169 </li><li jsinstance="3"> |
170 <a href="#H2-7">Communication </a> | 170 <a href="#H2-7">Communication between pages </a> |
171 <ol> | 171 <ol> |
172 <li jsinstance="*0" style="display: none; "> | 172 <li jsinstance="*0" style="display: none; "> |
173 <a>h3Name</a> | 173 <a>h3Name</a> |
174 </li> | 174 </li> |
175 </ol> | 175 </ol> |
176 </li><li jsinstance="*4"> | 176 </li><li jsinstance="*4"> |
177 <a href="#H2-8"> Summary </a> | 177 <a href="#H2-8"> Summary </a> |
178 <ol> | 178 <ol> |
179 <li jsinstance="*0" style="display: none; "> | 179 <li jsinstance="*0" style="display: none; "> |
180 <a>h3Name</a> | 180 <a>h3Name</a> |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
222 </div> | 222 </div> |
223 </ol> | 223 </ol> |
224 </div> | 224 </div> |
225 <!-- /TABLE OF CONTENTS --> | 225 <!-- /TABLE OF CONTENTS --> |
226 | 226 |
227 <!-- STATIC CONTENT PLACEHOLDER --> | 227 <!-- STATIC CONTENT PLACEHOLDER --> |
228 <div id="static"><div id="pageData-title" class="pageData">Overview</div
> | 228 <div id="static"><div id="pageData-title" class="pageData">Overview</div
> |
229 <div id="pageData-showTOC" class="pageData">true</div> | 229 <div id="pageData-showTOC" class="pageData">true</div> |
230 | 230 |
231 <p> | 231 <p> |
232 Please read this page; | 232 Read this page! |
233 it has vital information about the extension architecture. | 233 It has vital information about the extension architecture. |
234 If you get bored or restless, | 234 Once you've finished this page |
235 take a break! | 235 and the |
236 We suggest bouncing between this page | 236 <a href="getstarted.html">Getting Started</a> tutorial, |
237 and tutorials | 237 you'll be all set to start writing extensions. |
238 such as <a href="getstarted.html">Getting Started</a> | |
239 and <a href="tut_debugging.html">Debugging</a>. | |
240 </p> | 238 </p> |
241 | 239 |
242 | 240 |
243 <h2 id="what">The basics</h2> | 241 <h2 id="what">The basics</h2> |
244 | 242 |
245 <p> | 243 <p> |
246 An extension is a zipped bundle of files — | 244 An extension is a zipped bundle of files — |
247 HTML, CSS, JavaScript, images, and anything else you need — | 245 HTML, CSS, JavaScript, images, and anything else you need — |
248 that adds functionality to the Google Chrome browser. | 246 that adds functionality to the Google Chrome browser. |
249 Because an extension is just a special kind of web page, | 247 Extensions are essentially web pages, |
250 it can use all the APIs | 248 and they can use all the APIs |
251 that the browser provides | 249 that the browser provides |
252 to web pages and apps, | 250 to web pages, |
253 from XMLHttpRequest to JSON to localStorage. | 251 from XMLHttpRequest to JSON to HTML5 local storage. |
254 </p> | 252 </p> |
255 | 253 |
256 <p> | 254 <p> |
257 Extensions can add UI to Google Chrome, | 255 Many extensions add UI to Google Chrome, |
258 in the form of | 256 in the form of |
259 <a href="toolstrip.html">toolstrips</a> (toolbar additions) | 257 <a href="toolstrip.html">toolstrips</a> (toolbar additions) |
260 and <a href="pageActions.html">page actions</a> | 258 or <a href="pageActions.html">page actions</a> |
261 (clickable badges in the address bar). | 259 (clickable badges in the address bar). |
262 Extensions can also interact programmatically | 260 Extensions can also interact programmatically |
263 with browser features such as | 261 with browser features such as |
264 <a href="bookmarks.html">bookmarks</a> | 262 <a href="bookmarks.html">bookmarks</a> |
265 and <a href="tabs.html">tabs</a>. | 263 and <a href="tabs.html">tabs</a>. |
| 264 To interact with web pages or servers, |
| 265 extensions can use |
| 266 <a href="content_scripts.html">content scripts</a> or |
| 267 <a href="xhr.html">cross-origin XMLHttpRequests</a>. |
266 </p> | 268 </p> |
267 | 269 |
268 <p> | 270 <p> |
269 To find a complete list of extension features, | 271 See the <a href="devguide.html">Developer's Guide</a> |
| 272 for a complete list of extension features, |
270 with implementation details | 273 with implementation details |
271 for each one, | 274 for each one. |
272 see the <a href="devguide.html">Developer's Guide</a>. | |
273 </p> | 275 </p> |
274 | 276 |
275 | 277 |
276 <h2 id="files">Files</h2> | 278 <h2 id="files">Files</h2> |
277 <p> | 279 <p> |
278 Each extension has the following files: | 280 Each extension has the following files: |
279 <!-- PENDING: This could use a picture --> | 281 <!-- PENDING: This could use a picture --> |
280 </p> | 282 </p> |
281 | 283 |
282 <ul> | 284 <ul> |
283 <li>A <b>manifest file</b></li> | 285 <li>A <b>manifest file</b></li> |
284 <li>One or more <b>HTML files</b> (unless the extension is a theme)</li> | 286 <li>One or more <b>HTML files</b> (unless the extension is a theme)</li> |
285 <li><em>Optional:</em> One or more <b>JavaScript files</b></li> | 287 <li><em>Optional:</em> One or more <b>JavaScript files</b></li> |
286 <li><em>Optional:</em> Any other files your extension needs — for example, ima
ge files</li> | 288 <li><em>Optional:</em> Any other files your extension needs — |
| 289 for example, image files</li> |
287 </ul> | 290 </ul> |
288 | 291 |
289 <p> | 292 <p> |
290 While you're working on your extension, | 293 While you're working on your extension, |
291 you put all these files into a single folder. | 294 you put all these files into a single folder. |
292 When you distribute your extension, | 295 When you distribute your extension, |
293 the contents of the folder are packaged into a special zipfile | 296 the contents of the folder are packaged into a special ZIP file |
294 that has a <code>.crx</code> suffix, | 297 that has a <code>.crx</code> suffix, |
295 as described in <a href="packaging.html">Packaging</a>. | 298 as described in <a href="packaging.html">Packaging</a>. |
296 </p> | 299 </p> |
297 | 300 |
298 | 301 |
299 <a name="H3-2"></a><h3>Referring to files</h3> | 302 <a name="H3-2"></a><h3>Referring to files</h3> |
300 | 303 |
301 <p> | 304 <p> |
302 You can put any file you like into an extension, | 305 You can put any file you like into an extension, |
303 but how do you use it? | 306 but how do you use it? |
304 Usually, | 307 Usually, |
305 you can refer to the file using a relative URL, | 308 you can refer to the file using a relative URL, |
306 just as you would in an ordinary HTML page. | 309 just as you would in an ordinary HTML page. |
307 Here's an example of referring to | 310 Here's an example of referring to |
308 a file named <code>myimage.png</code> | 311 a file named <code>myimage.png</code> |
309 that's in a subfolder named <code>images</code>. | 312 that's in a subfolder named <code>images</code>. |
310 </p> | 313 </p> |
311 | 314 |
312 <pre><img <b>src="images/myimage.png"</b> style="width:auto; height:auto"> | 315 <pre><img <b>src="images/myimage.png"</b>> |
313 </pre> | 316 </pre> |
314 | 317 |
315 <p> | 318 <p> |
316 As you might notice while you use the Google Chrome debugger, | 319 As you might notice while you use the Google Chrome debugger, |
317 every file in an extension is also accessible by an absolute URL like this: | 320 every file in an extension is also accessible by an absolute URL like this: |
318 </p> | 321 </p> |
319 | 322 |
320 <blockquote> | 323 <blockquote> |
321 <b>chrome-extension://</b><em><extensionID></em><b>/</b><em><pathToFile
></em> | 324 <b>chrome-extension://</b><em><extensionID></em><b>/</b><em><pathToFile
></em> |
322 </blockquote> | 325 </blockquote> |
323 | 326 |
324 <p> | 327 <p> |
325 In that URL, the <em><extensionID></em> is a unique identifier | 328 In that URL, the <em><extensionID></em> is a unique identifier |
326 that the extension system generates for each extension. | 329 that the extension system generates for each extension. |
327 You can see the IDs for all your loaded extensions | 330 You can see the IDs for all your loaded extensions |
328 by going to the URL <b>chrome://extensions/</b>. | 331 by going to the URL <b>chrome://extensions/</b>. |
329 The <em><pathToFile></em> is the location of the file | 332 The <em><pathToFile></em> is the location of the file |
330 under the extension's top folder; | 333 under the extension's top folder; |
331 it's the same as the relative URL. | 334 it's the same as the relative URL. |
332 </p> | 335 </p> |
333 | 336 |
334 <p> | 337 <p class="comment"> |
335 For example, assume your extension has | 338 [PENDING: Should mention/reflect/link to |
336 the ID <b>aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</b> | 339 <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n">in
ternationalization</a> |
337 and the files shown in the following figure: | 340 when it's ready.] |
338 </p> | |
339 | |
340 <pre><span class="tbd">[PENDING: someday this will be a real figure]</span> | |
341 toolstrip.html | |
342 styles.css | |
343 images: | |
344 myimage.png | |
345 ... | |
346 other: | |
347 more.html | |
348 morestyles.css | |
349 ... | |
350 </pre> | |
351 | |
352 <p> | |
353 Here's a table that shows the relative and absolute URLs of these files. | |
354 Keep in mind that the relative URL is the same no matter where you're using it — | |
355 the relative URL of <code>myimage.png</code> is | |
356 <b>images/myimage.png</b>, | |
357 no matter whether it's being used by | |
358 <code>toolstrip.html</code> or <code>other/more.html</code>. | |
359 </p> | |
360 | |
361 <table> | |
362 <tbody><tr> | |
363 <th> File </th> | |
364 <th> Relative URL </th> | |
365 <th> Absolute URL </th> | |
366 </tr> | |
367 <tr> | |
368 <td> toolstrip.html </td> | |
369 <td> toolstrip.html </td> | |
370 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/toolstrip.html </td> | |
371 </tr> | |
372 <tr> | |
373 <td> styles.css </td> | |
374 <td> styles.css </td> | |
375 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/styles.css </td> | |
376 </tr> | |
377 <tr> | |
378 <td> myimage.png </td> | |
379 <td> images/myimage.png </td> | |
380 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/images/myimage.png </
td> | |
381 </tr> | |
382 <tr> | |
383 <td> more.html </td> | |
384 <td> other/more.html </td> | |
385 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/more.html </td> | |
386 </tr> | |
387 <tr> | |
388 <td> morestyles.css </td> | |
389 <td> other/morestyles.css </td> | |
390 <td> chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/other/morestyles.css
</td> | |
391 </tr> | |
392 </tbody></table> | |
393 | |
394 <p class="tbd"> | |
395 [PENDING: Mention/reflect/link to | |
396 <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n">in
ternationalization</a>] | |
397 </p> | 341 </p> |
398 | 342 |
399 | 343 |
400 <a name="H3-3"></a><h3>The manifest file</h3> | 344 <a name="H3-3"></a><h3>The manifest file</h3> |
401 | 345 |
402 <p> | 346 <p> |
403 The manifest file, called <code>manifest.json</code>, | 347 The manifest file, called <code>manifest.json</code>, |
404 gives information about the extension, | 348 gives information about the extension, |
405 such as the most important files | 349 such as the most important files |
406 and the capabilities that the extension might use. | 350 and the capabilities that the extension might use. |
(...skipping 11 matching lines...) Expand all Loading... |
418 }</pre> | 362 }</pre> |
419 | 363 |
420 <p> | 364 <p> |
421 For details, see | 365 For details, see |
422 <a href="manifest.html">Manifest Files</a>. | 366 <a href="manifest.html">Manifest Files</a>. |
423 </p> | 367 </p> |
424 | 368 |
425 <h2 id="arch">Architecture</h2> | 369 <h2 id="arch">Architecture</h2> |
426 | 370 |
427 <p> | 371 <p> |
428 The following pictures shows the web pages associated with a typical extension | 372 Remember that extensions are essentially web pages. |
429 (in this case, a simple toolstrip). | 373 The following figure shows what |
430 The first figure shows what an extension might look like | 374 a simple extension with a toolstrip |
| 375 might look like |
431 when there's a single browser window. | 376 when there's a single browser window. |
| 377 The toolstrip (T1) is at the bottom of the window. |
| 378 The HTML and JavaScript code for T1 |
| 379 is in a web page |
| 380 (<code>toolstrip.html</code>). |
432 </p> | 381 </p> |
433 | 382 |
434 <p class="tbd"> [PENDING: image goes here] </p> | 383 <img src="images/arch-1.gif"> |
435 | 384 |
436 <p> | 385 <p> |
437 The next figure shows that all the code in the extension's main HTML file | 386 Each time the user creates a new window, |
438 is duplicated each time you create a new window. | 387 the browser creates new toolstrips, page actions, and so on. |
439 In other words, each window has its own widgets for the extension, | 388 Each new bit of UI gets its own web page, |
440 which means each window adds another web page for that extension. | 389 which means that toolstrips (for example) |
| 390 that are in different windows can have different states. |
| 391 In the following figure, |
| 392 the two toolstrips (T1 and T2) |
| 393 are associated with two separate web pages, |
| 394 both of which contain code from <code>toolstrip.html</code>. |
| 395 This means that although both toolstrips use the same code, |
| 396 one can be blue while the other is green. |
441 </p> | 397 </p> |
442 | 398 |
443 <p class="tbd"> [PENDING: image goes here] </p> | 399 <img src="images/arch-2.gif"> |
444 | |
445 <p> | |
446 To more easily coordinate all these web pages and to avoid duplication, | |
447 you should design your extension | |
448 so that most of the code — | |
449 especially the state of the extension — | |
450 is in a <em>background page</em>, | |
451 as shown in the following figure. | |
452 </p> | |
453 | |
454 <p class="tbd"> [PENDING: image goes here] </p> | |
455 | 400 |
456 | 401 |
457 <h3 id="background">The background page</h3> | 402 <h3 id="background">The background page</h3> |
| 403 |
458 <p> | 404 <p> |
459 Any non-trivial extension can (and probably should) | 405 If your extension's web pages need to communicate |
460 have a background page. | 406 or otherwise share information — |
| 407 for example, if a browser event |
| 408 can affect more than just one window's toolstrip — |
| 409 the extension can use a background page. |
| 410 The following figure shows a background page |
| 411 (<code>background.html</code>) |
| 412 that controls |
| 413 the toolstrips in an extension. |
| 414 </p> |
| 415 |
| 416 <img src="images/arch-3.gif"> |
| 417 |
| 418 <p> |
461 The background page is an invisible page | 419 The background page is an invisible page |
462 where you put the main logic of the extension. | 420 where you can put the main logic of the extension. |
463 The extension's other pages should have | 421 The extension's other pages should have |
464 only the code that's necessary | 422 only the code that's necessary |
465 to show the state of the extension | 423 to show the state of the extension |
466 and to get input from the user.</p> | 424 and to get input from the user.</p> |
467 | 425 |
468 <p> | 426 <p> |
469 An extension's background page exists | |
470 before any of the extension's other pages exist. | |
471 It continues to exist as long as the browser is running | |
472 and the extension is installed, | |
473 even if other pages and windows go away. | |
474 </p> | |
475 | |
476 <p> | |
477 Your extension's UI — | |
478 its toolstrips, page actions, and so on — | |
479 should be dumb views. | |
480 When the view needs some state, | |
481 it should request it from the background page. | |
482 When the background page notices some state change, | |
483 it should update all the views. | |
484 </p> | |
485 | |
486 <p> | |
487 For more information, see | 427 For more information, see |
488 <a href="background_pages.html">Background Pages</a>. | 428 <a href="background_pages.html">Background Pages</a>. |
489 </p> | 429 </p> |
490 | 430 |
491 <h3 id="contentScripts">Content scripts</h3> | 431 <h3 id="contentScripts">Content scripts</h3> |
492 | 432 |
493 <p> | 433 <p> |
494 If you want your extension to interact with web pages, | 434 If your extension needs to interact with web pages, |
495 you need a content script. | 435 then it needs a <em>content script</em>. |
496 Content scripts are JavaScript files that run in the context of web pages. | 436 Content scripts are JavaScript files that run in the context of web pages. |
497 By using the standard Document Object Model (DOM), | 437 Using the standard |
498 they can read details of the web pages the browser visits, | 438 <a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document Object Model</a> |
| 439 (DOM), |
| 440 content scripts can read details of the web pages the browser visits, |
499 and they can make changes to the pages. | 441 and they can make changes to the pages. |
500 </p> | 442 </p> |
501 | 443 |
| 444 <p> |
| 445 In the following figure, |
| 446 the content script |
| 447 can read and modify |
| 448 the DOM for the web page displayed in Window 1. |
| 449 If the toolstrip's UI needs to change |
| 450 to reflect the web page's contents, |
| 451 the content script can request that change |
| 452 by sending a message to the parent extension. |
| 453 </p> |
| 454 |
| 455 <img src="images/arch-cs.gif"> |
| 456 |
502 <p class="comment"> | 457 <p class="comment"> |
503 [PENDING: add an architectural figure here, | 458 [PENDING: Add overview of message passing.] |
504 showing the extension's pages, a web page, and the content script | |
505 interacting with the web page. explain the figure.] | |
506 </p> | 459 </p> |
507 | 460 |
508 <p> | 461 <p> |
509 For more information, | 462 For more information, |
510 see <a href="content_scripts.html">Content Scripts</a>. | 463 see <a href="content_scripts.html">Content Scripts</a>. |
511 </p> | 464 </p> |
512 | 465 |
513 | 466 |
514 <a name="H2-7"></a><h2>Communication </h2> | 467 <a name="H2-7"></a><h2>Communication between pages </h2> |
515 | 468 |
516 <p> | 469 <p> |
517 Two kinds of communication happen within an extension: | 470 The HTML pages within an extension often need to communicate. |
| 471 An example is when the background page tells |
| 472 UI pages (such as toolstrips) |
| 473 to update their appearance. |
| 474 Because all of an extension's pages |
| 475 execute in same process on the same thread, |
| 476 the pages can make direct function calls to each other. |
518 </p> | 477 </p> |
519 | 478 |
520 <ul> | |
521 <li> | |
522 Communication <b>between pages</b> in the extension. | |
523 <br> | |
524 For example, sometimes the background page | |
525 needs to update all the UI pages | |
526 to reflect a change in the extension's state. | |
527 </li> | |
528 <li> | |
529 Communication <b>between content scripts and the extension</b>. | |
530 <br> | |
531 For example, | |
532 <span class="tbd">[PENDING: typical use case goes here]</span>. | |
533 See <a href="content_scripts.html">Content Scripts</a> | |
534 for information about this type of communication. | |
535 </li> | |
536 </ul> | |
537 | |
538 <p> | 479 <p> |
539 Here are some keys to communication between an extension's pages: | 480 To find pages in the extension, use |
| 481 <a href="extension.html"><code>chrome.extension</code></a> |
| 482 methods such as |
| 483 <code>getViews()</code>, |
| 484 <code>getBackgroundPage()</code>, |
| 485 and <code>getToolstrips()</code>. |
| 486 Once a page has a reference to other pages within the extension, |
| 487 the first page can invoke functions on the other pages. |
| 488 It can even manipulate their DOMs. |
540 </p> | 489 </p> |
541 | 490 |
542 <ul> | |
543 <li> | |
544 All the extension's pages execute in same process, | |
545 on the same thread. | |
546 </li> | |
547 <li> | |
548 Extension pages can use | |
549 <a href="extension.html"><code>chrome.extension</code></a> | |
550 methods such as | |
551 <code>getViews()</code>, | |
552 <code>getBackgroundPage()</code>, | |
553 and <code>getToolstrips()</code> | |
554 to get access to the extension's pages. | |
555 </li> | |
556 <li> | |
557 Once you have references to an extension's pages, | |
558 you can manipulate the DOM for each page. | |
559 </li> | |
560 <li> | |
561 You can also make direct function calls to the pages, | |
562 as shown in the following example. | |
563 </li> | |
564 </ul> | |
565 | |
566 <p> | 491 <p> |
567 Here's an example of | 492 Here's an example of |
568 communication between toolstrips and the background page. | 493 communication between toolstrips and the background page. |
569 </p> | 494 </p> |
570 | 495 |
571 <pre>//In background_page.html: | 496 <pre>//In background.html: |
572 function updateUI(checked) { | 497 function updateUI(checked) { |
573 var toolstrips = chrome.extension.getToolstrips(); | 498 var toolstrips = chrome.extension.getToolstrips(); |
574 for (var i in toolstrips) { | 499 for (var i in toolstrips) { |
575 if (toolstrips[i].enableCheckbox) | 500 if (toolstrips[i].enableCheckbox) |
576 toolstrips[i].enableCheckbox(checked); | 501 toolstrips[i].enableCheckbox(checked); |
577 } | 502 } |
578 } | 503 } |
579 | 504 |
580 //In toolstrip.html: | 505 //In toolstrip.html: |
581 function enableCheckbox(checked) { | 506 function enableCheckbox(checked) { |
(...skipping 194 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
776 urchinTracker(); | 701 urchinTracker(); |
777 } | 702 } |
778 catch(e) {/* urchinTracker not available. */} | 703 catch(e) {/* urchinTracker not available. */} |
779 </script> | 704 </script> |
780 <!-- end analytics --> | 705 <!-- end analytics --> |
781 | 706 |
782 </div> <!-- /pageFooter --> | 707 </div> <!-- /pageFooter --> |
783 </div> <!-- /container --> | 708 </div> <!-- /container --> |
784 </body></html> | 709 </body></html> |
785 | 710 |
OLD | NEW |