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> 373Once you've finished this page 374and the 375<a href="getstarted.html">Getting Started</a> tutorial, 376you'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, 382so unless otherwise stated, 383everything in this page applies to packaged apps. 384</p> 385 386<h2 id="what">The basics</h2> 387 388<p> 389An extension is a zipped bundle of files—HTML, 390CSS, JavaScript, images, and anything else you need—that 391adds functionality to the Google Chrome browser. 392Extensions are essentially web pages, 393and they can use all the 394<a href="api_other.html">APIs that the browser provides to web pages</a>, 395from XMLHttpRequest to JSON to HTML5. 396</p> 397 398<p> 399Extensions 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>. 402Extensions can also interact programmatically 403with browser features such as 404<a href="bookmarks.html">bookmarks</a> 405and <a href="tabs.html">tabs</a>. 406</p> 407 408<h3 id="extension-ui">Extension UIs</h3> 409 410<p> 411Many extensions—but not packaged apps—add 412UI to Google Chrome in the form of 413<a href="browserAction.html">browser actions</a> 414or <a href="pageAction.html">page actions</a>. 415Each extension can have at most one browser action or page action. 416Choose a <b>browser action</b> when the extension is relevant to most pages. 417Choose a <b>page action</b> when the extension's icon 418should appear or disappear, 419depending 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> 458Extensions (and packaged apps) can also present a UI in other ways, 459such as adding to the Chrome context menu, 460providing an options page, 461or using a content script that changes how pages look. 462See the <a href="devguide.html">Developer's Guide</a> 463for a complete list of extension features, 464with links to implementation details 465for each one. 466</p> 467 468 469<h3 id="packagedapp-ui">Packaged app UIs</h3> 470 471<p> 472A packaged app usually presents its main functionality using 473an HTML page that's bundled into the app. 474For example, the following packaged app 475displays 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> 481For more information, 482see <a href="apps.html">Packaged Apps</a>. 483</p> 484 485<h2 id="files">Files</h2> 486<p> 487Each 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 needs—for 496 example, image files</li> 497</ul> 498 499<p> 500While you're working on your extension, 501you put all these files into a single folder. 502When you distribute your extension, 503the contents of the folder are packaged into a special ZIP file 504that has a <code>.crx</code> suffix. 505If you upload your extension using the 506<a href="https://chrome.google.com/webstore/developer/dashboard">Chrome Developer Dashboard</a>, 507the <code>.crx</code> file is created for you. 508For details on distributing extensions, 509see <a href="hosting.html">Hosting</a>. 510</p> 511 512 513<h3 id="relative-urls">Referring to files</h3> 514 515<p> 516You can put any file you like into an extension, 517but how do you use it? 518Usually, 519you can refer to the file using a relative URL, 520just as you would in an ordinary HTML page. 521Here's an example of referring to 522a file named <code>myimage.png</code> 523that'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> 530As you might notice while you use the Google Chrome debugger, 531every 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> 539In that URL, the <em><extensionID></em> is a unique identifier 540that the extension system generates for each extension. 541You can see the IDs for all your loaded extensions 542by going to the URL <b>chrome://extensions</b>. 543The <em><pathToFile></em> is the location of the file 544under the extension's top folder; 545it'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> 554The manifest file, called <code>manifest.json</code>, 555gives information about the extension, 556such as the most important files 557and the capabilities that the extension might use. 558Here's a typical manifest file for a browser action 559that 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> 577For details, see 578<a href="manifest.html">Manifest Files</a>. 579</p> 580 581<h2 id="arch">Architecture</h2> 582 583<p> 584Many extensions have a <em>background page</em>, 585an invisible page 586that holds the main logic of the extension. 587An extension can also contain other pages 588that present the extension's UI. 589If an extension needs to interact with web pages that the user loads 590(as opposed to pages that are included in the extension), 591then the extension must use a content script. 592</p> 593 594 595<h3 id="background_page">The background page</h3> 596 597<p> 598The following figure shows a browser 599that has at least two extensions installed: 600a browser action (yellow icon) 601and a page action (blue icon). 602Both the browser action and the page action 603have background pages defined by HTML files. 604This figure shows the browser action's background page, 605which is defined by <code>background.html</code> 606and has JavaScript code that controls 607the 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> 613Although background pages can be useful, 614don't use one if you don't need it. 615Background pages are always open, 616so when a user installs many extensions that have background pages, 617Chrome'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> 625Here 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> 650See <a href="background_pages.html">Background Pages</a> 651for more details. 652</p> 653 654<h3 id="pages">UI pages</h3> 655 656<p> 657Extensions can contain ordinary HTML pages that display the extension's UI. 658For example, a browser action can have a popup, 659which is implemented by an HTML file. 660Any extension can have an options page, 661which lets users customize how the extension works. 662Another type of special page is the override page. 663And finally, you can 664use <a href="tabs.html#method-create">chrome.tabs.create()</a> 665or <code>window.open()</code> 666to display any other HTML files that are in the extension. 667</p> 668 669<p> 670The HTML pages inside an extension 671have complete access to each other's DOMs, 672and they can invoke functions on each other. 673</p> 674 675<!-- PENDING: Change the following example and figure 676to use something that's not a popup? 677(It might lead people to think that popups need background pages.) --> 678 679<p> 680The following figure shows the architecture 681of a browser action's popup. 682The popup's contents are a web page 683defined by an HTML file 684(<code>popup.html</code>). 685This extension also happens to have a background page 686(<code>background.html</code>). 687The popup doesn't need to duplicate code 688that's in the background page 689because 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> 695See <a href="browserAction.html">Browser Actions</a>, 696<a href="options.html">Options</a>, 697<a href="override.html">Override Pages</a>, 698and the <a href="#pageComm">Communication between pages</a> section 699for more details. 700</p> 701 702 703<h3 id="contentScripts">Content scripts</h3> 704 705<p> 706If your extension needs to interact with web pages, 707then it needs a <em>content script</em>. 708A content script is some JavaScript 709that executes in the context of a page 710that's been loaded into the browser. 711Think of a content script as part of that loaded page, 712not 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 718Each extension runs in its own process. 719To have rich interaction with a web page, however, 720the extension must be able to 721run some code in the web page's process. 722Extensions accomplish this with content scripts.] 723--> 724 725<p> 726Content scripts can read details of the web pages the browser visits, 727and they can make changes to the pages. 728In the following figure, 729the content script 730can read and modify 731the DOM for the displayed web page. 732It 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> 738Content scripts aren't completely cut off from their parent extensions. 739A content script can exchange messages with its parent extension, 740as the arrows in the following figure show. 741For example, a content script might send a message 742whenever it finds an RSS feed in a browser page. 743Or a background page might send a message 744asking 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> 752For more information, 753see <a href="content_scripts.html">Content Scripts</a>. 754</p> 755 756 757<h2 id="apis"> Using the chrome.* APIs </h2> 758 759<p> 760In addition to having access to all the APIs that web pages and apps can use, 761extensions can also use Chrome-only APIs 762(often called <em>chrome.* APIs</em>) 763that allow tight integration with the browser. 764For example, any extension or web app can use the 765standard <code>window.open()</code> method to open a URL. 766But if you want to specify which window that URL should be displayed in, 767your extension can use the Chrome-only 768<a href="tabs.html#method-create">chrome.tabs.create()</a> 769method instead. 770</p> 771 772<h3 id="sync"> Asynchronous vs. synchronous methods </h3> 773<p> 774Most methods in the chrome.* APIs are <b>asynchronous</b>: 775they return immediately, without waiting for the operation to finish. 776If you need to know the outcome of that operation, 777then you pass a callback function into the method. 778That callback is executed later (potentially <em>much</em> later), 779sometime after the method returns. 780Here's an example of the signature for an asynchronous method: 781</p> 782 783<p> 784<code> 785chrome.tabs.create(object <em>createProperties</em>, function <em>callback</em>) 786</code> 787</p> 788 789<p> 790Other chrome.* methods are <b>synchronous</b>. 791Synchronous methods never have a callback 792because they don't return until they've completed all their work. 793Often, synchronous methods have a return type. 794Consider the 795<a href="extension.html#method-getBackgroundPage">chrome.extensions.getBackgroundPage()</a> method: 796</p> 797 798<p> 799<code> 800DOMWindow chrome.extension.getBackgroundPage() 801</code> 802</p> 803 804<p> 805This method has no callback and a return type of <code>DOMWindow</code> 806because it synchronously returns the background page 807and performs no other, asynchronous work. 808</p> 809 810 811<h3 id="sync-example"> Example: Using a callback </h3> 812 813<p> 814Say you want to navigate 815the user's currently selected tab to a new URL. 816To do this, you need to get the current tab's ID 817(using <a href="tabs.html#method-getSelected">chrome.tabs.getSelected()</a>) 818and 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> 823If <code>getSelected()</code> were synchronous, 824you 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> 834That approach fails 835because <code>getSelected()</code> is asynchronous. 836It returns without waiting for its work to complete, 837and it doesn't even return a value 838(although some asynchronous methods do). 839You can tell that <code>getSelected()</code> is asynchronous 840by the <em>callback</em> parameter in its signature: 841 842</p><p> 843<code> 844chrome.tabs.getSelected(integer <em>windowId</em>, function <em>callback</em>) 845</code> 846</p> 847 848<p> 849To fix the preceding code, 850you must use that callback parameter. 851The following code shows 852how to define a callback function 853that gets the results from <code>getSelected()</code> 854(as a parameter named <code>tab</code>) 855and 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> 866In this example, the lines are executed in the following order: 1, 4, 2. 867The callback function specified to <code>getSelected</code> is called 868(and line 2 executed) 869only after information about the currently selected tab is available, 870which is sometime after <code>getSelected()</code> returns. 871Although <code>update()</code> is asynchronous, 872this example doesn't use its callback parameter, 873since 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> 880For more information, see the 881<a href="api_index.html">chrome.* API docs</a> 882and 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> 892The HTML pages within an extension often need to communicate. 893<!-- [PENDING: For example, ...] --> 894Because all of an extension's pages 895execute in same process on the same thread, 896the pages can make direct function calls to each other. 897</p> 898 899<p> 900To find pages in the extension, use 901<a href="extension.html"><code>chrome.extension</code></a> 902methods such as 903<code>getViews()</code> and 904<code>getBackgroundPage()</code>. 905Once a page has a reference to other pages within the extension, 906the first page can invoke functions on the other pages, 907and 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> 916Extensions can save data using 917the HTML5 <a href="http://dev.w3.org/html5/webstorage/">web storage API</a> 918(such as <code>localStorage</code>) 919or by making server requests that result in saving data. 920Whenever you want to save something, 921first consider whether it's 922from a window that's in incognito mode. 923By default, extensions don't run in incognito windows, 924and packaged apps <em>do</em>. 925You need to consider what a user expects 926from your extension or packaged app 927when the browser is incognito. 928</p> 929 930<p> 931<em>Incognito mode</em> promises that the window will leave no tracks. 932When dealing with data from incognito windows, 933do your best to honor this promise. 934For example, if your extension normally 935saves browsing history to the cloud, 936don't save history from incognito windows. 937On the other hand, you can store 938your extension's settings from any window, 939incognito or not. 940</p> 941 942<p class="note"> 943<b>Rule of thumb:</b> 944If a piece of data might show where a user 945has been on the web or what the user has done, 946don't store it if it's from an incognito window. 947</p> 948 949<p> 950To detect whether a window is in incognito mode, 951check 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. 954For example: 955</p> 956 957<pre>var bgPage = chrome.extension.getBackgroundPage(); 958 959function 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> 971Now that you've been introduced to extensions, 972you should be ready to write your own. 973Here 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
