background_pages.html revision dc0f95d653279beabeb9817299e2902918ba123e
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>Background Pages - 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><a href="overview.html">Overview</a></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 class="leftNavSelected">Background Pages</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">Background Pages</h1> 255 </div> 256 <!-- TABLE OF CONTENTS --> 257 <div id="toc"> 258 <h2>Contents</h2> 259 <ol> 260 <li> 261 <a href="#manifest">Manifest</a> 262 <ol> 263 <li style="display: none; "> 264 <a>h3Name</a> 265 </li> 266 </ol> 267 </li><li> 268 <a href="#H2-1">Details</a> 269 <ol> 270 <li style="display: none; "> 271 <a>h3Name</a> 272 </li> 273 </ol> 274 </li><li> 275 <a href="#example">Example</a> 276 <ol> 277 <li style="display: none; "> 278 <a>h3Name</a> 279 </li> 280 </ol> 281 </li> 282 <li style="display: none; "> 283 <a href="#apiReference">API reference</a> 284 <ol> 285 <li> 286 <a href="#properties">Properties</a> 287 <ol> 288 <li> 289 <a href="#property-anchor">propertyName</a> 290 </li> 291 </ol> 292 </li> 293 <li> 294 <a>Methods</a> 295 <ol> 296 <li> 297 <a href="#method-anchor">methodName</a> 298 </li> 299 </ol> 300 </li> 301 <li> 302 <a>Events</a> 303 <ol> 304 <li> 305 <a href="#event-anchor">eventName</a> 306 </li> 307 </ol> 308 </li> 309 <li> 310 <a href="#types">Types</a> 311 <ol> 312 <li> 313 <a href="#id-anchor">id</a> 314 </li> 315 </ol> 316 </li> 317 </ol> 318 </li> 319 </ol> 320 </div> 321 <!-- /TABLE OF CONTENTS --> 322 323 <!-- Standard content lead-in for experimental API pages --> 324 <p id="classSummary" style="display: none; "> 325 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 326 </p> 327 328 <!-- STATIC CONTENT PLACEHOLDER --> 329 <div id="static"><div id="pageData-name" class="pageData">Background Pages</div> 330<div id="pageData-showTOC" class="pageData">true</div> 331 332<p> 333A common need for extensions is to have 334a single long-running script to manage some task or state. 335Background pages to the rescue. 336</p> 337 338<p> 339As the <a href="overview.html#arch">architecture overview</a> explains, 340the background page is an HTML page that runs in the extension process. 341It exists for the lifetime of your extension, 342and only one instance of it at a time is active. 343</p> 344 345<p> 346In a typical extension with a background page, 347the UI — 348for example, the browser action or page action 349and any options page — 350is implemented by dumb views. 351When the view needs some state, 352it requests the state from the background page. 353When the background page notices a state change, 354the background page tells the views to update. 355</p> 356 357<h2 id="manifest">Manifest</h2> 358 359<p> 360Register your background page in the 361<a href="manifest.html">extension manifest</a> 362like this: 363</p> 364 365<pre>{ 366 "name": "My extension", 367 ... 368 <b>"background_page": "background.html"</b>, 369 ... 370}</pre> 371 372<p> 373If you need the browser to start up early—so 374you can display notifications, for example—then 375you might also want to specify the 376<a href="manifest.html#permissions">"background" permission</a>. 377</p> 378 379 380<a name="H2-1"></a><h2>Details</h2> 381 382<p> 383You can communicate between your various pages using direct script calls, 384similar to how frames can communicate. 385The <a href="extension.html#method-getViews"><code>chrome.extension.getViews()</code></a> method 386returns a list of window objects 387for every active page belonging to your extension, 388and the 389<a href="extension.html#method-getBackgroundPage"><code>chrome.extension.getBackgroundPage()</code></a> method 390returns the background page. 391</p> 392 393<h2 id="example">Example</h2> 394 395<p> 396The following code snippet demonstrates 397how the background page 398can interact with other pages in the extension. 399It also shows how you can use 400the background page to handle events 401such as user clicks. 402</p> 403 404<p> 405The extension in this example 406has a background page 407and multiple pages created 408(with 409<a href="tabs.html#method-create"><code>chrome.tabs.create()</code></a>) 410from a file named <code>image.html</code>. 411<!-- [PENDING: Once we have our set of samples, we should point to the example this is from and to other relevant examples. This is currently untested code derived from the screenshot sample.] --> 412</p> 413 414<pre><em>//In the background page:</em> 415<html> 416 <script> 417 //React when a browser action's icon is clicked. 418 chrome.browserAction.onClicked.addListener(function(tab) { 419 var viewTabUrl = chrome.extension.getURL('image.html'); 420 var imageUrl = <em>/* an image's URL */</em>; 421 422 //Look through all the pages in this extension to find one we can use. 423 var views = chrome.extension.getViews(); 424 for (var i = 0; i < views.length; i++) { 425 var view = views[i]; 426 427 //If this view has the right URL and hasn't been used yet... 428 if (view.location.href == viewTabUrl && !view.imageAlreadySet) { 429 430 //...call one of its functions and set a property. 431 view.setImageUrl(imageUrl); 432 view.imageAlreadySet = true; 433 break; //we're done 434 } 435 } 436 }); 437 </script> 438</html> 439 440<em>//In image.html:</em> 441<html> 442 <script> 443 function setImageUrl(url) { 444 document.getElementById('target').src = url; 445 } 446 </script> 447 448 <body> 449 <p> 450 Image here: 451 </p> 452 453 <img id="target" src="white.png" width="640" height="480"> 454 455 </body> 456</html> 457</pre> 458 459</div> 460 461 <!-- API PAGE --> 462 <div class="apiPage" style="display: none; "> 463 <a name="apiReference"></a> 464 <h2>API reference: chrome.apiname </h2> 465 466 <!-- PROPERTIES --> 467 <div class="apiGroup"> 468 <a name="properties"></a> 469 <h3 id="properties">Properties</h3> 470 471 <div> 472 <a></a> 473 <h4>getLastError</h4> 474 <div class="summary"> 475 <!-- Note: intentionally longer 80 columns --> 476 <span>chrome.extension</span><span>lastError</span> 477 </div> 478 <div> 479 </div> 480 </div> 481 482 </div> <!-- /apiGroup --> 483 484 <!-- METHODS --> 485 <div id="methodsTemplate" class="apiGroup"> 486 <a></a> 487 <h3>Methods</h3> 488 489 <!-- iterates over all functions --> 490 <div class="apiItem"> 491 <a></a> <!-- method-anchor --> 492 <h4>method name</h4> 493 494 <div class="summary"><span>void</span> 495 <!-- Note: intentionally longer 80 columns --> 496 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 497 <var><span></span></var></span>)</div> 498 499 <div class="description"> 500 <p class="todo">Undocumented.</p> 501 <p> 502 A description from the json schema def of the function goes here. 503 </p> 504 505 <!-- PARAMETERS --> 506 <h4>Parameters</h4> 507 <dl> 508 <div> 509 <div> 510 </div> 511 </div> 512 </dl> 513 514 <!-- RETURNS --> 515 <h4>Returns</h4> 516 <dl> 517 <div> 518 <div> 519 </div> 520 </div> 521 </dl> 522 523 <!-- CALLBACK --> 524 <div> 525 <div> 526 <h4>Callback function</h4> 527 <p> 528 The callback <em>parameter</em> should specify a function 529 that looks like this: 530 </p> 531 <p> 532 If you specify the <em>callback</em> parameter, it should 533 specify a function that looks like this: 534 </p> 535 536 <!-- Note: intentionally longer 80 columns --> 537 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 538 <dl> 539 <div> 540 <div> 541 </div> 542 </div> 543 </dl> 544 </div> 545 </div> 546 547 <!-- MIN_VERSION --> 548 <p> 549 This function was added in version <b><span></span></b>. 550 If you require this function, the manifest key 551 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 552 can ensure that your extension won't be run in an earlier browser version. 553 </p> 554 </div> <!-- /description --> 555 556 </div> <!-- /apiItem --> 557 558 </div> <!-- /apiGroup --> 559 560 <!-- EVENTS --> 561 <div id="eventsTemplate" class="apiGroup"> 562 <a></a> 563 <h3>Events</h3> 564 <!-- iterates over all events --> 565 <div class="apiItem"> 566 <a></a> 567 <h4>event name</h4> 568 569 <div class="summary"> 570 <!-- Note: intentionally longer 80 columns --> 571 <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>); 572 </div> 573 574 <div class="description"> 575 <p class="todo">Undocumented.</p> 576 <p> 577 A description from the json schema def of the event goes here. 578 </p> 579 580 <!-- PARAMETERS --> 581 <div> 582 <h4>Parameters</h4> 583 <dl> 584 <div> 585 <div> 586 </div> 587 </div> 588 </dl> 589 </div> 590 </div> <!-- /decription --> 591 592 </div> <!-- /apiItem --> 593 594 </div> <!-- /apiGroup --> 595 596 <!-- TYPES --> 597 <div class="apiGroup"> 598 <a name="types"></a> 599 <h3 id="types">Types</h3> 600 601 <!-- iterates over all types --> 602 <div class="apiItem"> 603 <a></a> 604 <h4>type name</h4> 605 606 <div> 607 </div> 608 609 </div> <!-- /apiItem --> 610 611 </div> <!-- /apiGroup --> 612 613 </div> <!-- /apiPage --> 614 </div> <!-- /gc-pagecontent --> 615 </div> <!-- /g-section --> 616 </div> <!-- /codesiteContent --> 617 <div id="gc-footer" --=""> 618 <div class="text"> 619 <p> 620 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 621 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 622 Attribution 3.0 License</a>, and code samples are licensed under the 623 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 624 </p> 625 <p> 626 ©2011 Google 627 </p> 628 629<!-- begin analytics --> 630<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 631<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 632 633<script type="text/javascript"> 634 // chrome doc tracking 635 try { 636 var engdocs = _gat._getTracker("YT-10763712-2"); 637 engdocs._trackPageview(); 638 } catch(err) {} 639 640 // code.google.com site-wide tracking 641 try { 642 _uacct="UA-18071-1"; 643 _uanchor=1; 644 _uff=0; 645 urchinTracker(); 646 } 647 catch(e) {/* urchinTracker not available. */} 648</script> 649<!-- end analytics --> 650 </div> 651 </div> <!-- /gc-footer --> 652 </div> <!-- /gc-container --> 653</body></html> 654
