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 3 across api docs and should be edited only with knowledge of the 4 templating mechanism. 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 7 authored overview content. 8 4) The <body>.innerHTML is also generated by an offline step so that this 9 page may easily be indexed by search engines. 10 --><html xmlns="http://www.w3.org/1999/xhtml"><head> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 14 <script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js"> 15 </script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script> 18 <script type="text/javascript" src="js/sidebar.js"></script> 19 <title>Overview - Google Chrome Extensions - Google Code</title></head> 20 <body> <div id="gc-container" class="labs"> 21 <div id="devModeWarning"> 22 You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files. 23 </div> 24 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 25 <!-- In particular, sub-templates that recurse, must be used by allowing 26 jstemplate to make a copy of the template in this section which 27 are not operated on by way of the jsskip="true" --> 28 <div style="display:none"> 29 30 <!-- VALUE --> 31 <div id="valueTemplate"> 32 <dt> 33 <var>paramName</var> 34 <em> 35 36 <!-- TYPE --> 37 <div style="display:inline"> 38 ( 39 <span class="optional">optional</span> 40 <span class="enum">enumerated</span> 41 <span id="typeTemplate"> 42 <span> 43 <a> Type</a> 44 </span> 45 <span> 46 <span> 47 array of <span><span></span></span> 48 </span> 49 <span>paramType</span> 50 <span></span> 51 </span> 52 </span> 53 ) 54 </div> 55 56 </em> 57 </dt> 58 <dd class="todo"> 59 Undocumented. 60 </dd> 61 <dd> 62 Description of this parameter from the json schema. 63 </dd> 64 <dd> 65 This parameter was added in version 66 <b><span></span></b>. 67 You must omit this parameter in earlier versions, 68 and you may omit it in any version. If you require this 69 parameter, the manifest key 70 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 71 can ensure that your extension won't be run in an earlier browser version. 72 </dd> 73 74 <!-- OBJECT PROPERTIES --> 75 <dd> 76 <dl> 77 <div> 78 <div> 79 </div> 80 </div> 81 </dl> 82 </dd> 83 84 <!-- OBJECT METHODS --> 85 <dd> 86 <div></div> 87 </dd> 88 89 <!-- OBJECT EVENT FIELDS --> 90 <dd> 91 <div></div> 92 </dd> 93 94 <!-- FUNCTION PARAMETERS --> 95 <dd> 96 <div></div> 97 </dd> 98 99 </div> <!-- /VALUE --> 100 101 <div id="functionParametersTemplate"> 102 <h5>Parameters</h5> 103 <dl> 104 <div> 105 <div> 106 </div> 107 </div> 108 </dl> 109 </div> 110 </div> <!-- /SUBTEMPLATES --> 111 112 <a id="top"></a> 113 <div id="skipto"> 114 <a href="#gc-pagecontent">Skip to page content</a> 115 <a href="#gc-toc">Skip to main navigation</a> 116 </div> 117 <!-- API HEADER --> 118 <table id="header" width="100%" cellspacing="0" border="0"> 119 <tbody><tr> 120 <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td> 121 <td valign="middle" width="100%" style="padding-left:0.6em;"> 122 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 123 <div id="gsc-search-box"> 124 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 125 <input type="hidden" name="ie" value="UTF-8"> 126 <input type="text" name="q" value="" size="55"> 127 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 128 <br> 129 <span class="greytext">e.g. "page action" or "tabs"</span> 130 </div> 131 </form> 132 133 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 134 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 135 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 136 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 137 </td> 138 </tr> 139 </tbody></table> 140 141 <div id="codesiteContent" class=""> 142 143 <a id="gc-topnav-anchor"></a> 144 <div id="gc-topnav"> 145 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 146 <ul id="home" class="gc-topnav-tabs"> 147 <li id="home_link"> 148 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 149 </li> 150 <li id="docs_link"> 151 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 152 </li> 153 <li id="faq_link"> 154 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 155 </li> 156 <li id="samples_link"> 157 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 158 </li> 159 <li id="group_link"> 160 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 161 </li> 162 </ul> 163 </div> <!-- end gc-topnav --> 164 165 <div class="g-section g-tpl-170"> 166 <!-- SIDENAV --> 167 <div class="g-unit g-first" id="gc-toc"> 168 <ul> 169 <li><a href="getstarted.html">Getting Started</a></li> 170 <li class="leftNavSelected">Overview</li> 171 <li><a href="whats_new.html">What's New?</a></li> 172 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 173 <ul> 174 <li>Browser UI 175 <ul> 176 <li><a href="browserAction.html">Browser Actions</a></li> 177 <li><a href="contextMenus.html">Context Menus</a></li> 178 <li><a href="notifications.html">Desktop Notifications</a></li> 179 <li><a href="omnibox.html">Omnibox</a></li> 180 <li><a href="options.html">Options Pages</a></li> 181 <li><a href="override.html">Override Pages</a></li> 182 <li><a href="pageAction.html">Page Actions</a></li> 183 </ul> 184 </li> 185 <li>Browser Interaction 186 <ul> 187 <li><a href="bookmarks.html">Bookmarks</a></li> 188 <li><a href="cookies.html">Cookies</a></li> 189 <li><a href="events.html">Events</a></li> 190 <li><a href="history.html">History</a></li> 191 <li><a href="management.html">Management</a></li> 192 <li><a href="tabs.html">Tabs</a></li> 193 <li><a href="windows.html">Windows</a></li> 194 </ul> 195 </li> 196 <li>Implementation 197 <ul> 198 <li><a href="a11y.html">Accessibility</a></li> 199 <li><a href="background_pages.html">Background Pages</a></li> 200 <li><a href="content_scripts.html">Content Scripts</a></li> 201 <li><a href="xhr.html">Cross-Origin XHR</a></li> 202 <li><a href="idle.html">Idle</a></li> 203 <li><a href="i18n.html">Internationalization</a></li> 204 <li><a href="messaging.html">Message Passing</a></li> 205 <li><a href="npapi.html">NPAPI Plugins</a></li> 206 </ul> 207 </li> 208 <li>Finishing 209 <ul> 210 <li><a href="hosting.html">Hosting</a></li> 211 <li><a href="external_extensions.html">Other Deployment Options</a></li> 212 </ul> 213 </li> 214 </ul> 215 </li> 216 <li><h2><a href="apps.html">Packaged Apps</a></h2></li> 217 <li><h2><a href="tutorials.html">Tutorials</a></h2> 218 <ul> 219 <li><a href="tut_debugging.html">Debugging</a></li> 220 <li><a href="tut_analytics.html">Google Analytics</a></li> 221 <li><a href="tut_oauth.html">OAuth</a></li> 222 </ul> 223 </li> 224 <li><h2>Reference</h2> 225 <ul> 226 <li>Formats 227 <ul> 228 <li><a href="manifest.html">Manifest Files</a></li> 229 <li><a href="match_patterns.html">Match Patterns</a></li> 230 </ul> 231 </li> 232 <li><a href="permission_warnings.html">Permission Warnings</a></li> 233 <li><a href="api_index.html">chrome.* APIs</a></li> 234 <li><a href="api_other.html">Other APIs</a></li> 235 </ul> 236 </li> 237 <li><h2><a href="samples.html">Samples</a></h2></li> 238 <div class="line"> </div> 239 <li><h2>More</h2> 240 <ul> 241 <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> 242 <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li> 243 <li><a href="themes.html">Themes</a></li> 244 </ul> 245 </li> 246 </ul> 247 </div> 248 <script> 249 initToggles(); 250 </script> 251 252 <div class="g-unit" id="gc-pagecontent"> 253 <div id="pageTitle"> 254 <h1 class="page_title">Overview</h1> 255 </div> 256 <!-- TABLE OF CONTENTS --> 257 <div id="toc"> 258 <h2>Contents</h2> 259 <ol> 260 <li> 261 <a href="#what">The basics</a> 262 <ol> 263 <li> 264 <a href="#extension-ui">Extension UIs</a> 265 </li><li> 266 <a href="#packagedapp-ui">Packaged app UIs</a> 267 </li> 268 </ol> 269 </li><li> 270 <a href="#files">Files</a> 271 <ol> 272 <li> 273 <a href="#relative-urls">Referring to files</a> 274 </li><li> 275 <a href="#H3-5">The manifest file</a> 276 </li> 277 </ol> 278 </li><li> 279 <a href="#arch">Architecture</a> 280 <ol> 281 <li> 282 <a href="#background_page">The background page</a> 283 </li><li> 284 <a href="#pages">UI pages</a> 285 </li><li> 286 <a href="#contentScripts">Content scripts</a> 287 </li> 288 </ol> 289 </li><li> 290 <a href="#apis"> Using the chrome.* APIs </a> 291 <ol> 292 <li> 293 <a href="#sync"> Asynchronous vs. synchronous methods </a> 294 </li><li> 295 <a href="#sync-example"> Example: Using a callback </a> 296 </li><li> 297 <a href="#chrome-more"> More details </a> 298 </li> 299 </ol> 300 </li><li> 301 <a href="#pageComm">Communication between pages </a> 302 <ol> 303 <li style="display: none; "> 304 <a>h3Name</a> 305 </li> 306 </ol> 307 </li><li> 308 <a href="#incognito"> Saving data and incognito mode </a> 309 <ol> 310 <li style="display: none; "> 311 <a>h3Name</a> 312 </li> 313 </ol> 314 </li><li> 315 <a href="#now-what"> Now what? </a> 316 <ol> 317 <li style="display: none; "> 318 <a>h3Name</a> 319 </li> 320 </ol> 321 </li> 322 <li style="display: none; "> 323 <a href="#apiReference">API reference</a> 324 <ol> 325 <li> 326 <a href="#properties">Properties</a> 327 <ol> 328 <li> 329 <a href="#property-anchor">propertyName</a> 330 </li> 331 </ol> 332 </li> 333 <li> 334 <a>Methods</a> 335 <ol> 336 <li> 337 <a href="#method-anchor">methodName</a> 338 </li> 339 </ol> 340 </li> 341 <li> 342 <a>Events</a> 343 <ol> 344 <li> 345 <a href="#event-anchor">eventName</a> 346 </li> 347 </ol> 348 </li> 349 <li> 350 <a href="#types">Types</a> 351 <ol> 352 <li> 353 <a href="#id-anchor">id</a> 354 </li> 355 </ol> 356 </li> 357 </ol> 358 </li> 359 </ol> 360 </div> 361 <!-- /TABLE OF CONTENTS --> 362 363 <!-- Standard content lead-in for experimental API pages --> 364 <p id="classSummary" style="display: none; "> 365 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 366 </p> 367 368 <!-- STATIC CONTENT PLACEHOLDER --> 369 <div id="static"><div id="pageData-name" class="pageData">Overview</div> 370 <div id="pageData-showTOC" class="pageData">true</div> 371 372 <p> 373 Once you've finished this page 374 and the 375 <a href="getstarted.html">Getting Started</a> tutorial, 376 you'll be all set to start writing extensions and packaged apps. 377 </p> 378 379 <p class="caution"> 380 <strong>Note:</strong> 381 <em>Packaged apps</em> are implemented as extensions, 382 so unless otherwise stated, 383 everything in this page applies to packaged apps. 384 </p> 385 386 <h2 id="what">The basics</h2> 387 388 <p> 389 An extension is a zipped bundle of filesHTML, 390 CSS, JavaScript, images, and anything else you needthat 391 adds functionality to the Google Chrome browser. 392 Extensions are essentially web pages, 393 and they can use all the 394 <a href="api_other.html">APIs that the browser provides to web pages</a>, 395 from XMLHttpRequest to JSON to HTML5. 396 </p> 397 398 <p> 399 Extensions can interact with web pages or servers using 400 <a href="content_scripts.html">content scripts</a> or 401 <a href="xhr.html">cross-origin XMLHttpRequests</a>. 402 Extensions can also interact programmatically 403 with browser features such as 404 <a href="bookmarks.html">bookmarks</a> 405 and <a href="tabs.html">tabs</a>. 406 </p> 407 408 <h3 id="extension-ui">Extension UIs</h3> 409 410 <p> 411 Many extensionsbut not packaged appsadd 412 UI to Google Chrome in the form of 413 <a href="browserAction.html">browser actions</a> 414 or <a href="pageAction.html">page actions</a>. 415 Each extension can have at most one browser action or page action. 416 Choose a <b>browser action</b> when the extension is relevant to most pages. 417 Choose a <b>page action</b> when the extension's icon 418 should appear or disappear, 419 depending on the page. 420 </p> 421 422 <table class="columns"> 423 <tbody><tr> 424 <td width="33%"> 425 <img src="images/overview/browser-action.png" width="147" height="100" alt="screenshot"> 426 </td> 427 <td width="33%"> 428 <img src="images/overview/page-action.png" width="147" height="100" alt="screenshot"> 429 </td> 430 <td> 431 <img src="images/overview/browser-action-with-popup.png" width="147" height="100" alt="screenshot"> 432 </td> 433 </tr> 434 435 <tr> 436 <td> 437 This <a href="samples.html#gmail">mail extension</a> 438 uses a <em>browser action</em> 439 (icon in the toolbar). 440 </td> 441 <td> 442 This <a href="samples.html#mappy">map extension</a> 443 uses a <em>page action</em> 444 (icon in the address bar) 445 and <em>content script</em> 446 (code injected into a web page). 447 </td> 448 <td> 449 This <a href="samples.html#news">news extension</a> 450 features a browser action that, 451 when clicked, 452 shows a <em>popup</em>. 453 </td> 454 </tr> 455 </tbody></table> 456 457 <p> 458 Extensions (and packaged apps) can also present a UI in other ways, 459 such as adding to the Chrome context menu, 460 providing an options page, 461 or using a content script that changes how pages look. 462 See the <a href="devguide.html">Developer's Guide</a> 463 for a complete list of extension features, 464 with links to implementation details 465 for each one. 466 </p> 467 468 469 <h3 id="packagedapp-ui">Packaged app UIs</h3> 470 471 <p> 472 A packaged app usually presents its main functionality using 473 an HTML page that's bundled into the app. 474 For example, the following packaged app 475 displays a Flash file within an HTML page. 476 </p> 477 478 <img src="images/overview/flash-app.png" width="372" height="300" alt="screenshot"> 479 480 <p> 481 For more information, 482 see <a href="apps.html">Packaged Apps</a>. 483 </p> 484 485 <h2 id="files">Files</h2> 486 <p> 487 Each extension has the following files: 488 <!-- PENDING: This could use a picture --> 489 </p> 490 491 <ul> 492 <li>A <b>manifest file</b></li> 493 <li>One or more <b>HTML files</b> (unless the extension is a theme)</li> 494 <li><em>Optional:</em> One or more <b>JavaScript files</b></li> 495 <li><em>Optional:</em> Any other files your extension needsfor 496 example, image files</li> 497 </ul> 498 499 <p> 500 While you're working on your extension, 501 you put all these files into a single folder. 502 When you distribute your extension, 503 the contents of the folder are packaged into a special ZIP file 504 that has a <code>.crx</code> suffix. 505 If you upload your extension using the 506 <a href="https://chrome.google.com/webstore/developer/dashboard">Chrome Developer Dashboard</a>, 507 the <code>.crx</code> file is created for you. 508 For details on distributing extensions, 509 see <a href="hosting.html">Hosting</a>. 510 </p> 511 512 513 <h3 id="relative-urls">Referring to files</h3> 514 515 <p> 516 You can put any file you like into an extension, 517 but how do you use it? 518 Usually, 519 you can refer to the file using a relative URL, 520 just as you would in an ordinary HTML page. 521 Here's an example of referring to 522 a file named <code>myimage.png</code> 523 that's in a subfolder named <code>images</code>. 524 </p> 525 526 <pre><img <b>src="images/myimage.png"</b>> 527 </pre> 528 529 <p> 530 As you might notice while you use the Google Chrome debugger, 531 every file in an extension is also accessible by an absolute URL like this: 532 </p> 533 534 <blockquote> 535 <b>chrome-extension://</b><em><extensionID></em><b>/</b><em><pathToFile></em> 536 </blockquote> 537 538 <p> 539 In that URL, the <em><extensionID></em> is a unique identifier 540 that the extension system generates for each extension. 541 You can see the IDs for all your loaded extensions 542 by going to the URL <b>chrome://extensions</b>. 543 The <em><pathToFile></em> is the location of the file 544 under the extension's top folder; 545 it's the same as the relative URL. 546 </p> 547 548 <!-- [PENDING: Should mention/reflect/link to <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n">internationalization</a> when it's ready.] --> 549 550 551 <a name="H3-5"></a><h3>The manifest file</h3> 552 553 <p> 554 The manifest file, called <code>manifest.json</code>, 555 gives information about the extension, 556 such as the most important files 557 and the capabilities that the extension might use. 558 Here's a typical manifest file for a browser action 559 that uses information from google.com: 560 </p> 561 562 <pre>{ 563 "name": "My Extension", 564 "version": "2.1", 565 "description": "Gets information from Google.", 566 "icons": { "128": "icon_128.png" }, 567 "background_page": "bg.html", 568 "permissions": ["http://*.google.com/", "https://*.google.com/"], 569 "browser_action": { 570 "default_title": "", 571 "default_icon": "icon_19.png", 572 "default_popup": "popup.html" 573 } 574 }</pre> 575 576 <p> 577 For details, see 578 <a href="manifest.html">Manifest Files</a>. 579 </p> 580 581 <h2 id="arch">Architecture</h2> 582 583 <p> 584 Many extensions have a <em>background page</em>, 585 an invisible page 586 that holds the main logic of the extension. 587 An extension can also contain other pages 588 that present the extension's UI. 589 If an extension needs to interact with web pages that the user loads 590 (as opposed to pages that are included in the extension), 591 then the extension must use a content script. 592 </p> 593 594 595 <h3 id="background_page">The background page</h3> 596 597 <p> 598 The following figure shows a browser 599 that has at least two extensions installed: 600 a browser action (yellow icon) 601 and a page action (blue icon). 602 Both the browser action and the page action 603 have background pages defined by HTML files. 604 This figure shows the browser action's background page, 605 which is defined by <code>background.html</code> 606 and has JavaScript code that controls 607 the behavior of the browser action in both windows. 608 </p> 609 610 <img src="images/overview/arch-1.gif" width="232" height="168" alt="Two windows and a box representing a background page (background.html). One window has a yellow icon; the other has both a yellow icon and a blue icon. The yellow icons are connected to the background page."> 611 612 <p> 613 Although background pages can be useful, 614 don't use one if you don't need it. 615 Background pages are always open, 616 so when a user installs many extensions that have background pages, 617 Chrome's performance can suffer. 618 </p> 619 620 <!-- PENDING: Perhaps show a picture of many background page processes. 621 This could build on a figure that shows the process architecture, 622 and perhaps the differences between packaged apps and extensions. --> 623 624 <p> 625 Here are some examples of extensions that usually 626 <b>do not need</b> a background page: 627 </p> 628 629 <ul> 630 <li> An extension with a browser action that 631 presents its UI solely through a popup 632 (and perhaps an options page). 633 </li> 634 <li> 635 An extension that provides an <em>override page</em>a 636 page that replaces a standard Chrome page. 637 </li> 638 <li> 639 An extension with a content script 640 that doesn't use cross-origin XMLHttpRequests or localStorage, 641 and that doesn't need to use 642 <a href="#apis">extension APIs</a>. 643 </li> 644 <li> 645 An extension that has no UI except for an options page. 646 </li> 647 </ul> 648 649 <p> 650 See <a href="background_pages.html">Background Pages</a> 651 for more details. 652 </p> 653 654 <h3 id="pages">UI pages</h3> 655 656 <p> 657 Extensions can contain ordinary HTML pages that display the extension's UI. 658 For example, a browser action can have a popup, 659 which is implemented by an HTML file. 660 Any extension can have an options page, 661 which lets users customize how the extension works. 662 Another type of special page is the override page. 663 And finally, you can 664 use <a href="tabs.html#method-create">chrome.tabs.create()</a> 665 or <code>window.open()</code> 666 to display any other HTML files that are in the extension. 667 </p> 668 669 <p> 670 The HTML pages inside an extension 671 have complete access to each other's DOMs, 672 and they can invoke functions on each other. 673 </p> 674 675 <!-- PENDING: Change the following example and figure 676 to use something that's not a popup? 677 (It might lead people to think that popups need background pages.) --> 678 679 <p> 680 The following figure shows the architecture 681 of a browser action's popup. 682 The popup's contents are a web page 683 defined by an HTML file 684 (<code>popup.html</code>). 685 This extension also happens to have a background page 686 (<code>background.html</code>). 687 The popup doesn't need to duplicate code 688 that's in the background page 689 because the popup can invoke functions on the background page. 690 </p> 691 692 <img src="images/overview/arch-2.gif" width="256" height="168" alt="A browser window containing a browser action that's displaying a popup. The popup's HTML file (popup.html) can communicate with the extension's background page (background.html)."> 693 694 <p> 695 See <a href="browserAction.html">Browser Actions</a>, 696 <a href="options.html">Options</a>, 697 <a href="override.html">Override Pages</a>, 698 and the <a href="#pageComm">Communication between pages</a> section 699 for more details. 700 </p> 701 702 703 <h3 id="contentScripts">Content scripts</h3> 704 705 <p> 706 If your extension needs to interact with web pages, 707 then it needs a <em>content script</em>. 708 A content script is some JavaScript 709 that executes in the context of a page 710 that's been loaded into the browser. 711 Think of a content script as part of that loaded page, 712 not as part of the extension it was packaged with 713 (its <em>parent extension</em>). 714 </p> 715 716 <!-- [PENDING: Consider explaining that the reason content scripts are separated from the extension is due to chrome's multiprocess design. Something like: 717 718 Each extension runs in its own process. 719 To have rich interaction with a web page, however, 720 the extension must be able to 721 run some code in the web page's process. 722 Extensions accomplish this with content scripts.] 723 --> 724 725 <p> 726 Content scripts can read details of the web pages the browser visits, 727 and they can make changes to the pages. 728 In the following figure, 729 the content script 730 can read and modify 731 the DOM for the displayed web page. 732 It cannot, however, modify the DOM of its parent extension's background page. 733 </p> 734 735 <img src="images/overview/arch-3.gif" width="238" height="169" alt="A browser window with a browser action (controlled by background.html) and a content script (controlled by contentscript.js)."> 736 737 <p> 738 Content scripts aren't completely cut off from their parent extensions. 739 A content script can exchange messages with its parent extension, 740 as the arrows in the following figure show. 741 For example, a content script might send a message 742 whenever it finds an RSS feed in a browser page. 743 Or a background page might send a message 744 asking a content script to change the appearance of its browser page. 745 </p> 746 747 <img src="images/overview/arch-cs.gif" width="238" height="194" alt="Like the previous figure, but showing more of the parent extension's files, as well as a communication path between the content script and the parent extension."> 748 749 <!-- [PENDING: Add overview of message passing.] --> 750 751 <p> 752 For more information, 753 see <a href="content_scripts.html">Content Scripts</a>. 754 </p> 755 756 757 <h2 id="apis"> Using the chrome.* APIs </h2> 758 759 <p> 760 In addition to having access to all the APIs that web pages and apps can use, 761 extensions can also use Chrome-only APIs 762 (often called <em>chrome.* APIs</em>) 763 that allow tight integration with the browser. 764 For example, any extension or web app can use the 765 standard <code>window.open()</code> method to open a URL. 766 But if you want to specify which window that URL should be displayed in, 767 your extension can use the Chrome-only 768 <a href="tabs.html#method-create">chrome.tabs.create()</a> 769 method instead. 770 </p> 771 772 <h3 id="sync"> Asynchronous vs. synchronous methods </h3> 773 <p> 774 Most methods in the chrome.* APIs are <b>asynchronous</b>: 775 they return immediately, without waiting for the operation to finish. 776 If you need to know the outcome of that operation, 777 then you pass a callback function into the method. 778 That callback is executed later (potentially <em>much</em> later), 779 sometime after the method returns. 780 Here's an example of the signature for an asynchronous method: 781 </p> 782 783 <p> 784 <code> 785 chrome.tabs.create(object <em>createProperties</em>, function <em>callback</em>) 786 </code> 787 </p> 788 789 <p> 790 Other chrome.* methods are <b>synchronous</b>. 791 Synchronous methods never have a callback 792 because they don't return until they've completed all their work. 793 Often, synchronous methods have a return type. 794 Consider the 795 <a href="extension.html#method-getBackgroundPage">chrome.extensions.getBackgroundPage()</a> method: 796 </p> 797 798 <p> 799 <code> 800 DOMWindow chrome.extension.getBackgroundPage() 801 </code> 802 </p> 803 804 <p> 805 This method has no callback and a return type of <code>DOMWindow</code> 806 because it synchronously returns the background page 807 and performs no other, asynchronous work. 808 </p> 809 810 811 <h3 id="sync-example"> Example: Using a callback </h3> 812 813 <p> 814 Say you want to navigate 815 the user's currently selected tab to a new URL. 816 To do this, you need to get the current tab's ID 817 (using <a href="tabs.html#method-getSelected">chrome.tabs.getSelected()</a>) 818 and then make that tab go to the new URL 819 (using <a href="tabs.html#method-update">chrome.tabs.update()</a>). 820 </p> 821 822 <p> 823 If <code>getSelected()</code> were synchronous, 824 you might write code like this: 825 </p> 826 827 <pre> <b>//THIS CODE DOESN'T WORK</b> 828 <span class="linenumber">1: </span>var tab = chrome.tabs.getSelected(null); <b>//WRONG!!!</b> 829 <span class="linenumber">2: </span>chrome.tabs.update(tab.id, {url:newUrl}); 830 <span class="linenumber">3: </span>someOtherFunction(); 831 </pre> 832 833 <p> 834 That approach fails 835 because <code>getSelected()</code> is asynchronous. 836 It returns without waiting for its work to complete, 837 and it doesn't even return a value 838 (although some asynchronous methods do). 839 You can tell that <code>getSelected()</code> is asynchronous 840 by the <em>callback</em> parameter in its signature: 841 842 </p><p> 843 <code> 844 chrome.tabs.getSelected(integer <em>windowId</em>, function <em>callback</em>) 845 </code> 846 </p> 847 848 <p> 849 To fix the preceding code, 850 you must use that callback parameter. 851 The following code shows 852 how to define a callback function 853 that gets the results from <code>getSelected()</code> 854 (as a parameter named <code>tab</code>) 855 and calls <code>update()</code>. 856 </p> 857 858 <pre> <b>//THIS CODE WORKS</b> 859 <span class="linenumber">1: </span>chrome.tabs.getSelected(null, <b>function(tab) {</b> 860 <span class="linenumber">2: </span> chrome.tabs.update(tab.id, {url:newUrl}); 861 <span class="linenumber">3: </span><b>}</b>); 862 <span class="linenumber">4: </span>someOtherFunction(); 863 </pre> 864 865 <p> 866 In this example, the lines are executed in the following order: 1, 4, 2. 867 The callback function specified to <code>getSelected</code> is called 868 (and line 2 executed) 869 only after information about the currently selected tab is available, 870 which is sometime after <code>getSelected()</code> returns. 871 Although <code>update()</code> is asynchronous, 872 this example doesn't use its callback parameter, 873 since we don't do anything about the results of the update. 874 </p> 875 876 877 <h3 id="chrome-more"> More details </h3> 878 879 <p> 880 For more information, see the 881 <a href="api_index.html">chrome.* API docs</a> 882 and watch this video: 883 </p> 884 885 <p> 886 <iframe title="YouTube video player" width="640" height="390" src="http://www.youtube.com/embed/bmxr75CV36A?rel=0" frameborder="0" allowfullscreen=""></iframe> 887 </p> 888 889 <h2 id="pageComm">Communication between pages </h2> 890 891 <p> 892 The HTML pages within an extension often need to communicate. 893 <!-- [PENDING: For example, ...] --> 894 Because all of an extension's pages 895 execute in same process on the same thread, 896 the pages can make direct function calls to each other. 897 </p> 898 899 <p> 900 To find pages in the extension, use 901 <a href="extension.html"><code>chrome.extension</code></a> 902 methods such as 903 <code>getViews()</code> and 904 <code>getBackgroundPage()</code>. 905 Once a page has a reference to other pages within the extension, 906 the first page can invoke functions on the other pages, 907 and it can manipulate their DOMs. 908 </p> 909 910 <!-- [PENDING: Here's an example of communication between xyz and the background page. (code example goes here)] --> 911 912 913 <h2 id="incognito"> Saving data and incognito mode </h2> 914 915 <p> 916 Extensions can save data using 917 the HTML5 <a href="http://dev.w3.org/html5/webstorage/">web storage API</a> 918 (such as <code>localStorage</code>) 919 or by making server requests that result in saving data. 920 Whenever you want to save something, 921 first consider whether it's 922 from a window that's in incognito mode. 923 By default, extensions don't run in incognito windows, 924 and packaged apps <em>do</em>. 925 You need to consider what a user expects 926 from your extension or packaged app 927 when the browser is incognito. 928 </p> 929 930 <p> 931 <em>Incognito mode</em> promises that the window will leave no tracks. 932 When dealing with data from incognito windows, 933 do your best to honor this promise. 934 For example, if your extension normally 935 saves browsing history to the cloud, 936 don't save history from incognito windows. 937 On the other hand, you can store 938 your extension's settings from any window, 939 incognito or not. 940 </p> 941 942 <p class="note"> 943 <b>Rule of thumb:</b> 944 If a piece of data might show where a user 945 has been on the web or what the user has done, 946 don't store it if it's from an incognito window. 947 </p> 948 949 <p> 950 To detect whether a window is in incognito mode, 951 check the <code>incognito</code> property of the relevant 952 <a href="tabs.html#type-Tab">Tab</a> or 953 <a href="windows.html#type-Window">Window</a> object. 954 For example: 955 </p> 956 957 <pre>var bgPage = chrome.extension.getBackgroundPage(); 958 959 function saveTabData(tab, data) { 960 if (tab.incognito) { 961 bgPage[tab.url] = data; // Persist data ONLY in memory 962 } else { 963 localStorage[tab.url] = data; // OK to store data 964 } 965 </pre> 966 967 968 <h2 id="now-what"> Now what? </h2> 969 970 <p> 971 Now that you've been introduced to extensions, 972 you should be ready to write your own. 973 Here are some ideas for where to go next: 974 </p> 975 976 <ul> 977 <li> <a href="getstarted.html">Tutorial: Getting Started</a> </li> 978 <li> <a href="tut_debugging.html">Tutorial: Debugging</a> </li> 979 <li> <a href="devguide.html">Developer's Guide</a> </li> 980 <li> <a href="http://dev.chromium.org/developers/design-documents/extensions/samples">Samples</a> </li> 981 <li> <a href="http://www.youtube.com/view_play_list?p=CA101D6A85FE9D4B">Videos</a>, 982 such as 983 <a href="http://www.youtube.com/watch?v=B4M_a7xejYI&feature=PlayList&p=CA101D6A85FE9D4B&index=6">Extension Message Passing</a> 984 </li> 985 </ul> 986 </div> 987 988 <!-- API PAGE --> 989 <div class="apiPage" style="display: none; "> 990 <a name="apiReference"></a> 991 <h2>API reference: chrome.apiname </h2> 992 993 <!-- PROPERTIES --> 994 <div class="apiGroup"> 995 <a name="properties"></a> 996 <h3 id="properties">Properties</h3> 997 998 <div> 999 <a></a> 1000 <h4>getLastError</h4> 1001 <div class="summary"> 1002 <!-- Note: intentionally longer 80 columns --> 1003 <span>chrome.extension</span><span>lastError</span> 1004 </div> 1005 <div> 1006 </div> 1007 </div> 1008 1009 </div> <!-- /apiGroup --> 1010 1011 <!-- METHODS --> 1012 <div id="methodsTemplate" class="apiGroup"> 1013 <a></a> 1014 <h3>Methods</h3> 1015 1016 <!-- iterates over all functions --> 1017 <div class="apiItem"> 1018 <a></a> <!-- method-anchor --> 1019 <h4>method name</h4> 1020 1021 <div class="summary"><span>void</span> 1022 <!-- Note: intentionally longer 80 columns --> 1023 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 1024 <var><span></span></var></span>)</div> 1025 1026 <div class="description"> 1027 <p class="todo">Undocumented.</p> 1028 <p> 1029 A description from the json schema def of the function goes here. 1030 </p> 1031 1032 <!-- PARAMETERS --> 1033 <h4>Parameters</h4> 1034 <dl> 1035 <div> 1036 <div> 1037 </div> 1038 </div> 1039 </dl> 1040 1041 <!-- RETURNS --> 1042 <h4>Returns</h4> 1043 <dl> 1044 <div> 1045 <div> 1046 </div> 1047 </div> 1048 </dl> 1049 1050 <!-- CALLBACK --> 1051 <div> 1052 <div> 1053 <h4>Callback function</h4> 1054 <p> 1055 The callback <em>parameter</em> should specify a function 1056 that looks like this: 1057 </p> 1058 <p> 1059 If you specify the <em>callback</em> parameter, it should 1060 specify a function that looks like this: 1061 </p> 1062 1063 <!-- Note: intentionally longer 80 columns --> 1064 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 1065 <dl> 1066 <div> 1067 <div> 1068 </div> 1069 </div> 1070 </dl> 1071 </div> 1072 </div> 1073 1074 <!-- MIN_VERSION --> 1075 <p> 1076 This function was added in version <b><span></span></b>. 1077 If you require this function, the manifest key 1078 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 1079 can ensure that your extension won't be run in an earlier browser version. 1080 </p> 1081 </div> <!-- /description --> 1082 1083 </div> <!-- /apiItem --> 1084 1085 </div> <!-- /apiGroup --> 1086 1087 <!-- EVENTS --> 1088 <div id="eventsTemplate" class="apiGroup"> 1089 <a></a> 1090 <h3>Events</h3> 1091 <!-- iterates over all events --> 1092 <div class="apiItem"> 1093 <a></a> 1094 <h4>event name</h4> 1095 1096 <div class="summary"> 1097 <!-- Note: intentionally longer 80 columns --> 1098 <span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>); 1099 </div> 1100 1101 <div class="description"> 1102 <p class="todo">Undocumented.</p> 1103 <p> 1104 A description from the json schema def of the event goes here. 1105 </p> 1106 1107 <!-- PARAMETERS --> 1108 <div> 1109 <h4>Parameters</h4> 1110 <dl> 1111 <div> 1112 <div> 1113 </div> 1114 </div> 1115 </dl> 1116 </div> 1117 </div> <!-- /decription --> 1118 1119 </div> <!-- /apiItem --> 1120 1121 </div> <!-- /apiGroup --> 1122 1123 <!-- TYPES --> 1124 <div class="apiGroup"> 1125 <a name="types"></a> 1126 <h3 id="types">Types</h3> 1127 1128 <!-- iterates over all types --> 1129 <div class="apiItem"> 1130 <a></a> 1131 <h4>type name</h4> 1132 1133 <div> 1134 </div> 1135 1136 </div> <!-- /apiItem --> 1137 1138 </div> <!-- /apiGroup --> 1139 1140 </div> <!-- /apiPage --> 1141 </div> <!-- /gc-pagecontent --> 1142 </div> <!-- /g-section --> 1143 </div> <!-- /codesiteContent --> 1144 <div id="gc-footer" --=""> 1145 <div class="text"> 1146 <p> 1147 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 1148 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 1149 Attribution 3.0 License</a>, and code samples are licensed under the 1150 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 1151 </p> 1152 <p> 1153 2011 Google 1154 </p> 1155 1156 <!-- begin analytics --> 1157 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 1158 <script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 1159 1160 <script type="text/javascript"> 1161 // chrome doc tracking 1162 try { 1163 var engdocs = _gat._getTracker("YT-10763712-2"); 1164 engdocs._trackPageview(); 1165 } catch(err) {} 1166 1167 // code.google.com site-wide tracking 1168 try { 1169 _uacct="UA-18071-1"; 1170 _uanchor=1; 1171 _uff=0; 1172 urchinTracker(); 1173 } 1174 catch(e) {/* urchinTracker not available. */} 1175 </script> 1176 <!-- end analytics --> 1177 </div> 1178 </div> <!-- /gc-footer --> 1179 </div> <!-- /gc-container --> 1180 </body></html> 1181
