background_pages.html revision 731df977c0511bca2206b5f333555b1205ff1f43
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 <title>Background Pages - Google Chrome Extensions - Google Code</title></head> 19 <body> <div id="gc-container" class="labs"> 20 <div id="devModeWarning"> 21 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. 22 </div> 23 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 24 <!-- In particular, sub-templates that recurse, must be used by allowing 25 jstemplate to make a copy of the template in this section which 26 are not operated on by way of the jsskip="true" --> 27 <div style="display:none"> 28 29 <!-- VALUE --> 30 <div id="valueTemplate"> 31 <dt> 32 <var>paramName</var> 33 <em> 34 35 <!-- TYPE --> 36 <div style="display:inline"> 37 ( 38 <span class="optional">optional</span> 39 <span class="enum">enumerated</span> 40 <span id="typeTemplate"> 41 <span> 42 <a> Type</a> 43 </span> 44 <span> 45 <span> 46 array of <span><span></span></span> 47 </span> 48 <span>paramType</span> 49 <span></span> 50 </span> 51 </span> 52 ) 53 </div> 54 55 </em> 56 </dt> 57 <dd class="todo"> 58 Undocumented. 59 </dd> 60 <dd> 61 Description of this parameter from the json schema. 62 </dd> 63 <dd> 64 This parameter was added in version 65 <b><span></span></b>. 66 You must omit this parameter in earlier versions, 67 and you may omit it in any version. If you require this 68 parameter, the manifest key 69 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 70 can ensure that your extension won't be run in an earlier browser version. 71 </dd> 72 73 <!-- OBJECT PROPERTIES --> 74 <dd> 75 <dl> 76 <div> 77 <div> 78 </div> 79 </div> 80 </dl> 81 </dd> 82 83 <!-- FUNCTION PARAMETERS --> 84 <dd> 85 <div></div> 86 </dd> 87 88 </div> <!-- /VALUE --> 89 90 <div id="functionParametersTemplate"> 91 <h5>Parameters</h5> 92 <dl> 93 <div> 94 <div> 95 </div> 96 </div> 97 </dl> 98 </div> 99 </div> <!-- /SUBTEMPLATES --> 100 101 <a id="top"></a> 102 <div id="skipto"> 103 <a href="#gc-pagecontent">Skip to page content</a> 104 <a href="#gc-toc">Skip to main navigation</a> 105 </div> 106 <!-- API HEADER --> 107 <table id="header" width="100%" cellspacing="0" border="0"> 108 <tbody><tr> 109 <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> 110 <td valign="middle" width="100%" style="padding-left:0.6em;"> 111 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 112 <div id="gsc-search-box"> 113 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 114 <input type="hidden" name="ie" value="UTF-8"> 115 <input type="text" name="q" value="" size="55"> 116 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 117 <br> 118 <span class="greytext">e.g. "page action" or "tabs"</span> 119 </div> 120 </form> 121 122 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 123 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 124 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 125 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 126 </td> 127 </tr> 128 </tbody></table> 129 130 <div id="codesiteContent" class=""> 131 132 <a id="gc-topnav-anchor"></a> 133 <div id="gc-topnav"> 134 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 135 <ul id="home" class="gc-topnav-tabs"> 136 <li id="home_link"> 137 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 138 </li> 139 <li id="docs_link"> 140 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 141 </li> 142 <li id="faq_link"> 143 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 144 </li> 145 <li id="samples_link"> 146 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 147 </li> 148 <li id="group_link"> 149 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 150 </li> 151 </ul> 152 </div> <!-- end gc-topnav --> 153 154 <div class="g-section g-tpl-170"> 155 <!-- SIDENAV --> 156 <div class="g-unit g-first" id="gc-toc"> 157 <ul> 158 <li><a href="getstarted.html">Getting Started</a></li> 159 <li><a href="overview.html">Overview</a></li> 160 <li><a href="whats_new.html">What's New?</a></li> 161 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 162 <ul> 163 <li>Browser UI 164 <ul> 165 <li><a href="browserAction.html">Browser Actions</a></li> 166 <li><a href="contextMenus.html">Context Menus</a></li> 167 <li><a href="notifications.html">Desktop Notifications</a></li> 168 <li><a href="options.html">Options Pages</a></li> 169 <li><a href="override.html">Override Pages</a></li> 170 <li><a href="pageAction.html">Page Actions</a></li> 171 <li><a href="themes.html">Themes</a></li> 172 </ul> 173 </li> 174 <li>Browser Interaction 175 <ul> 176 <li><a href="bookmarks.html">Bookmarks</a></li> 177 <li><a href="cookies.html">Cookies</a></li> 178 <li><a href="events.html">Events</a></li> 179 <li><a href="history.html">History</a></li> 180 <li><a href="management.html">Management</a></li> 181 <li><a href="tabs.html">Tabs</a></li> 182 <li><a href="windows.html">Windows</a></li> 183 </ul> 184 </li> 185 <li>Implementation 186 <ul> 187 <li><a href="a11y.html">Accessibility</a></li> 188 <li class="leftNavSelected">Background Pages</li> 189 <li><a href="content_scripts.html">Content Scripts</a></li> 190 <li><a href="xhr.html">Cross-Origin XHR</a></li> 191 <li><a href="idle.html">Idle</a></li> 192 <li><a href="i18n.html">Internationalization</a></li> 193 <li><a href="messaging.html">Message Passing</a></li> 194 <li><a href="npapi.html">NPAPI Plugins</a></li> 195 </ul> 196 </li> 197 <li>Finishing 198 <ul> 199 <li><a href="hosting.html">Hosting</a></li> 200 <li><a href="external_extensions.html">Other Deployment Options</a></li> 201 </ul> 202 </li> 203 </ul> 204 </li> 205 <li><h2><a href="tutorials.html">Tutorials</a></h2> 206 <ul> 207 <li><a href="tut_debugging.html">Debugging</a></li> 208 <li><a href="tut_analytics.html">Google Analytics</a></li> 209 <li><a href="tut_oauth.html">OAuth</a></li> 210 </ul> 211 </li> 212 <li><h2>Reference</h2> 213 <ul> 214 <li>Formats 215 <ul> 216 <li><a href="manifest.html">Manifest Files</a></li> 217 <li><a href="match_patterns.html">Match Patterns</a></li> 218 <!-- <li>Packages (.crx)</li> --> 219 </ul> 220 </li> 221 <li><a href="api_index.html">chrome.* APIs</a></li> 222 <li><a href="api_other.html">Other APIs</a></li> 223 </ul> 224 </li> 225 <li><h2><a href="samples.html">Samples</a></h2></li> 226 </ul> 227 </div> 228 229 <div class="g-unit" id="gc-pagecontent"> 230 <div id="pageTitle"> 231 <h1 class="page_title">Background Pages</h1> 232 </div> 233 <!-- TABLE OF CONTENTS --> 234 <div id="toc"> 235 <h2>Contents</h2> 236 <ol> 237 <li> 238 <a href="#manifest">Manifest</a> 239 <ol> 240 <li style="display: none; "> 241 <a>h3Name</a> 242 </li> 243 </ol> 244 </li><li> 245 <a href="#H2-1">Details</a> 246 <ol> 247 <li style="display: none; "> 248 <a>h3Name</a> 249 </li> 250 </ol> 251 </li><li> 252 <a href="#example">Example</a> 253 <ol> 254 <li style="display: none; "> 255 <a>h3Name</a> 256 </li> 257 </ol> 258 </li> 259 <li style="display: none; "> 260 <a href="#apiReference">API reference</a> 261 <ol> 262 <li> 263 <a href="#properties">Properties</a> 264 <ol> 265 <li> 266 <a href="#property-anchor">propertyName</a> 267 </li> 268 </ol> 269 </li> 270 <li> 271 <a href="#methods">Methods</a> 272 <ol> 273 <li> 274 <a href="#method-anchor">methodName</a> 275 </li> 276 </ol> 277 </li> 278 <li> 279 <a href="#events">Events</a> 280 <ol> 281 <li> 282 <a href="#event-anchor">eventName</a> 283 </li> 284 </ol> 285 </li> 286 <li> 287 <a href="#types">Types</a> 288 <ol> 289 <li> 290 <a href="#id-anchor">id</a> 291 </li> 292 </ol> 293 </li> 294 </ol> 295 </li> 296 </ol> 297 </div> 298 <!-- /TABLE OF CONTENTS --> 299 300 <!-- Standard content lead-in for experimental API pages --> 301 <p id="classSummary" style="display: none; "> 302 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 303 </p> 304 305 <!-- STATIC CONTENT PLACEHOLDER --> 306 <div id="static"><div id="pageData-name" class="pageData">Background Pages</div> 307<div id="pageData-showTOC" class="pageData">true</div> 308 309<p> 310A common need for extensions is to have 311a single long-running script to manage some task or state. 312Background pages to the rescue. 313</p> 314 315<p> 316As the <a href="overview.html#arch">architecture overview</a> explains, 317the background page is an HTML page that runs in the extension process. 318It exists for the lifetime of your extension, 319and only one instance of it at a time is active. 320</p> 321 322<p> 323In a typical extension with a background page, 324the UI — 325for example, the browser action or page action 326and any options page — 327is implemented by dumb views. 328When the view needs some state, 329it requests the state from the background page. 330When the background page notices a state change, 331the background page tells the views to update. 332</p> 333 334<h2 id="manifest">Manifest</h2> 335 336<p> 337Register your background page in the 338<a href="manifest.html">extension manifest</a> 339like this: 340</p> 341 342<pre>{ 343 "name": "My extension", 344 ... 345 <b>"background_page": "background.html"</b>, 346 ... 347}</pre> 348 349<a name="H2-1"></a><h2>Details</h2> 350 351<p> 352You can communicate between your various pages using direct script calls, 353similar to how frames can communicate. 354The <a href="extension.html#method-getViews"><code>chrome.extension.getViews()</code></a> method 355returns a list of window objects 356for every active page belonging to your extension, 357and the 358<a href="extension.html#method-getBackgroundPage"><code>chrome.extension.getBackgroundPage()</code></a> method 359returns the background page. 360</p> 361 362<h2 id="example">Example</h2> 363 364<p> 365The following code snippet demonstrates 366how the background page 367can interact with other pages in the extension. 368It also shows how you can use 369the background page to handle events 370such as user clicks. 371</p> 372 373<p> 374The extension in this example 375has a background page 376and multiple pages created 377(with 378<a href="tabs.html#method-create"><code>chrome.tabs.create()</code></a>) 379from a file named <code>image.html</code>. 380<!-- [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.] --> 381</p> 382 383<pre><em>//In the background page:</em> 384<html> 385 <script> 386 //React when a browser action's icon is clicked. 387 chrome.browserAction.onClicked.addListener(function(tab) { 388 var viewTabUrl = chrome.extension.getURL('image.html'); 389 var imageUrl = <em>/* an image's URL */</em>; 390 391 //Look through all the pages in this extension to find one we can use. 392 var views = chrome.extension.getViews(); 393 for (var i = 0; i < views.length; i++) { 394 var view = views[i]; 395 396 //If this view has the right URL and hasn't been used yet... 397 if (view.location.href == viewTabUrl && !view.imageAlreadySet) { 398 399 //...call one of its functions and set a property. 400 view.setImageUrl(imageUrl); 401 view.imageAlreadySet = true; 402 break; //we're done 403 } 404 } 405 }); 406 </script> 407</html> 408 409<em>//In image.html:</em> 410<html> 411 <script> 412 function setImageUrl(url) { 413 document.getElementById('target').src = url; 414 } 415 </script> 416 417 <body> 418 <p> 419 Image here: 420 </p> 421 422 <img id="target" src="white.png" width="640" height="480"> 423 424 </body> 425</html> 426</pre> 427 428</div> 429 430 <!-- API PAGE --> 431 <div class="apiPage" style="display: none; "> 432 <a name="apiReference"></a> 433 <h2>API reference: chrome.apiname </h2> 434 435 <!-- PROPERTIES --> 436 <div class="apiGroup"> 437 <a name="properties"></a> 438 <h3 id="properties">Properties</h3> 439 440 <div> 441 <a></a> 442 <h4>getLastError</h4> 443 <div class="summary"> 444 <!-- Note: intentionally longer 80 columns --> 445 <span>chrome.extension</span><span>lastError</span> 446 </div> 447 <div> 448 </div> 449 </div> 450 451 </div> <!-- /apiGroup --> 452 453 <!-- METHODS --> 454 <div class="apiGroup" id="methods"> 455 <a name="methods"></a> 456 <h3>Methods</h3> 457 458 <!-- iterates over all functions --> 459 <div class="apiItem"> 460 <a></a> <!-- method-anchor --> 461 <h4>method name</h4> 462 463 <div class="summary"><span>void</span> 464 <!-- Note: intentionally longer 80 columns --> 465 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 466 <var><span></span></var></span>)</div> 467 468 <div class="description"> 469 <p class="todo">Undocumented.</p> 470 <p> 471 A description from the json schema def of the function goes here. 472 </p> 473 474 <!-- PARAMETERS --> 475 <h4>Parameters</h4> 476 <dl> 477 <div> 478 <div> 479 </div> 480 </div> 481 </dl> 482 483 <!-- RETURNS --> 484 <h4>Returns</h4> 485 <dl> 486 <div> 487 <div> 488 </div> 489 </div> 490 </dl> 491 492 <!-- CALLBACK --> 493 <div> 494 <div> 495 <h4>Callback function</h4> 496 <p> 497 The callback <em>parameter</em> should specify a function 498 that looks like this: 499 </p> 500 <p> 501 If you specify the <em>callback</em> parameter, it should 502 specify a function that looks like this: 503 </p> 504 505 <!-- Note: intentionally longer 80 columns --> 506 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 507 <dl> 508 <div> 509 <div> 510 </div> 511 </div> 512 </dl> 513 </div> 514 </div> 515 516 <!-- MIN_VERSION --> 517 <p> 518 This function was added in version <b><span></span></b>. 519 If you require this function, the manifest key 520 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 521 can ensure that your extension won't be run in an earlier browser version. 522 </p> 523 </div> <!-- /description --> 524 525 </div> <!-- /apiItem --> 526 527 </div> <!-- /apiGroup --> 528 529 <!-- EVENTS --> 530 <div class="apiGroup"> 531 <a name="events"></a> 532 <h3 id="events">Events</h3> 533 534 <!-- iterates over all events --> 535 <div class="apiItem"> 536 <a></a> 537 <h4>event name</h4> 538 539 <div class="summary"> 540 <!-- Note: intentionally longer 80 columns --> 541 <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>); 542 </div> 543 544 <div class="description"> 545 <p class="todo">Undocumented.</p> 546 <p> 547 A description from the json schema def of the event goes here. 548 </p> 549 550 <!-- PARAMETERS --> 551 <h4>Parameters</h4> 552 <dl> 553 <div> 554 <div> 555 </div> 556 </div> 557 </dl> 558 559 </div> <!-- /decription --> 560 561 </div> <!-- /apiItem --> 562 563 </div> <!-- /apiGroup --> 564 565 <!-- TYPES --> 566 <div class="apiGroup"> 567 <a name="types"></a> 568 <h3 id="types">Types</h3> 569 570 <!-- iterates over all types --> 571 <div class="apiItem"> 572 <a></a> 573 <h4>type name</h4> 574 575 <div> 576 </div> 577 578 </div> <!-- /apiItem --> 579 580 </div> <!-- /apiGroup --> 581 582 </div> <!-- /apiPage --> 583 </div> <!-- /gc-pagecontent --> 584 </div> <!-- /g-section --> 585 </div> <!-- /codesiteContent --> 586 <div id="gc-footer" --=""> 587 <div class="text"> 588 <p> 589 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 590 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 591 Attribution 3.0 License</a>, and code samples are licensed under the 592 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 593 </p> 594 <p> 595 ©2010 Google 596 </p> 597 598<!-- begin analytics --> 599<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 600<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 601 602<script type="text/javascript"> 603 // chrome doc tracking 604 try { 605 var engdocs = _gat._getTracker("YT-10763712-2"); 606 engdocs._trackPageview(); 607 } catch(err) {} 608 609 // code.google.com site-wide tracking 610 try { 611 _uacct="UA-18071-1"; 612 _uanchor=1; 613 _uff=0; 614 urchinTracker(); 615 } 616 catch(e) {/* urchinTracker not available. */} 617</script> 618<!-- end analytics --> 619 </div> 620 </div> <!-- /gc-footer --> 621 </div> <!-- /gc-container --> 622</body></html> 623
