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>Override 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 class="leftNavSelected">Override Pages</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">Override 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="#tips">Tips</a> 269 <ol> 270 <li style="display: none; "> 271 <a>h3Name</a> 272 </li> 273 </ol> 274 </li><li> 275 <a href="#examples"> Examples </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">Override Pages</div> 330<div id="pageData-showTOC" class="pageData">true</div> 331 332<style> 333#pics { 334 margin:2em 1em 1.5em; 335} 336 337#pics td { 338 text-align:center; 339 width:50%!important; 340 border:none; 341 padding:0 1em; 342 font-size:90%; 343} 344 345#pics img { 346 width:188; 347 height:246; 348 border:none; 349} 350</style> 351 352<p> 353Override pages are a way to substitute an HTML file from your extension 354for a page that Google Chrome normally provides. 355In addition to HTML, 356an override page usually has CSS and JavaScript code. 357</p> 358 359<p> 360An extension can replace any one of the following pages: 361</p><ul> 362 <li> <b>Bookmark Manager:</b> 363 The page that appears when the user chooses 364 the Bookmark Manager menu item 365 from the wrench menu or, on Mac, 366 the Bookmark Manager item from the Bookmarks menu. 367 You can also get to this page by entering the URL 368 <b>chrome://bookmarks</b>. 369 </li> 370 371 <li> <b>History:</b> 372 The page that appears when the user 373 chooses the History menu item 374 from the Tools (wrench) menu or, on Mac, 375 the Show Full History item from the History menu. 376 You can also get to this page by entering the URL 377 <b>chrome://history</b>. 378 </li> 379 380 <li> <b>New Tab:</b> 381 The page that appears when the user creates a new tab or window. 382 You can also get to this page by entering the URL 383 <b>chrome://newtab</b>. 384 </li> 385</ul> 386<p></p> 387 388<p class="note"> 389<b>Note:</b> 390A single extension can override 391<b>only one page</b>. 392For example, an extension can't override both 393the Bookmark Manager and History pages. 394</p> 395 396<p> 397Incognito windows are treated specially. 398New Tab pages cannot be overridden in incognito windows. 399Other override pages work in incognito windows 400as long as the 401<a href="manifest.html#incognito">incognito</a> 402manifest property is set to "spanning" 403(which is the default value for extensions 404but not for packaged apps). 405See <a href="overview.html#incognito">Saving data and incognito mode</a> 406in the Overview for more details on how you should treat 407incognito windows. 408</p> 409 410<p> 411The following screenshots show the default New Tab page 412next to a custom New Tab page. 413</p> 414 415<table id="pics"> 416 <tbody><tr> 417 <td> <b>The default New Tab page</b> </td> 418 <td> <b>An alternative New Tab page</b> </td> 419 </tr> 420 <tr> 421 <td> 422 <img src="images/ntp-default.png" alt="default New Tab page" width="200" height="173"> 423 </td> 424 <td> 425 <img src="images/ntp-blank.png" alt="a blank New Tab page" width="200" height="173"> 426 </td> 427 </tr> 428</tbody></table> 429 430<h2 id="manifest">Manifest</h2> 431 432<p> 433Register an override page in the 434<a href="manifest.html">extension manifest</a> like this: 435</p> 436 437<pre>{ 438 "name": "My extension", 439 ... 440 441<b> "chrome_url_overrides" : { 442 "<em>pageToOverride</em>": "<em>myPage.html</em>" 443 }</b>, 444 ... 445}</pre> 446 447<p> 448For <code><em>pageToOverride</em></code>, substitute one of the following: 449</p> 450 451<ul> 452 <li> <code>bookmarks</code> 453 </li><li> <code>history</code> 454 </li><li> <code>newtab</code> 455</li></ul> 456 457 458<h2 id="tips">Tips</h2> 459 460<p> 461For an effective override page, follow these guidelines: 462</p> 463 464<ul> 465 <li> 466 <p> 467 <b>Make your page quick and small.</b> <br> 468 Users expect built-in browser pages to open instantly. 469 Avoid doing things that might take a long time. 470 For example, avoid synchronous fetches of network or database resources. 471 </p> 472 </li> 473 <li> 474 <p> 475 <b>Include a title in your page.</b> <br> 476 Otherwise people might see the URL of the page, 477 which could be confusing. 478 Here's an example of specifying the title: 479 <code><title>New Tab</title></code> 480 </p> 481 </li> 482 <li> 483 <p> 484 <b>Don't rely on the page having the keyboard focus.</b> <br> 485 The address bar always gets the focus first 486 when the user creates a new tab. 487 </p> 488 </li> 489 <li> 490 <p> 491 <b>Don't try to emulate the default New Tab page.</b> <br> 492 The APIs necessary to create 493 a slightly modified version of the default New Tab page — 494 with top pages, 495 recently closed pages, 496 tips, 497 a theme background image, 498 and so on — 499 don't exist yet. 500 Until they do, 501 you're better off trying to make something completely different. 502 </p> 503 </li> 504</ul> 505 506<h2 id="examples"> Examples </h2> 507 508<p> 509See the 510<a href="samples.html#chrome_url_overrides">override samples</a>. 511</p> 512</div> 513 514 <!-- API PAGE --> 515 <div class="apiPage" style="display: none; "> 516 <a name="apiReference"></a> 517 <h2>API reference: chrome.apiname </h2> 518 519 <!-- PROPERTIES --> 520 <div class="apiGroup"> 521 <a name="properties"></a> 522 <h3 id="properties">Properties</h3> 523 524 <div> 525 <a></a> 526 <h4>getLastError</h4> 527 <div class="summary"> 528 <!-- Note: intentionally longer 80 columns --> 529 <span>chrome.extension</span><span>lastError</span> 530 </div> 531 <div> 532 </div> 533 </div> 534 535 </div> <!-- /apiGroup --> 536 537 <!-- METHODS --> 538 <div id="methodsTemplate" class="apiGroup"> 539 <a></a> 540 <h3>Methods</h3> 541 542 <!-- iterates over all functions --> 543 <div class="apiItem"> 544 <a></a> <!-- method-anchor --> 545 <h4>method name</h4> 546 547 <div class="summary"><span>void</span> 548 <!-- Note: intentionally longer 80 columns --> 549 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 550 <var><span></span></var></span>)</div> 551 552 <div class="description"> 553 <p class="todo">Undocumented.</p> 554 <p> 555 A description from the json schema def of the function goes here. 556 </p> 557 558 <!-- PARAMETERS --> 559 <h4>Parameters</h4> 560 <dl> 561 <div> 562 <div> 563 </div> 564 </div> 565 </dl> 566 567 <!-- RETURNS --> 568 <h4>Returns</h4> 569 <dl> 570 <div> 571 <div> 572 </div> 573 </div> 574 </dl> 575 576 <!-- CALLBACK --> 577 <div> 578 <div> 579 <h4>Callback function</h4> 580 <p> 581 The callback <em>parameter</em> should specify a function 582 that looks like this: 583 </p> 584 <p> 585 If you specify the <em>callback</em> parameter, it should 586 specify a function that looks like this: 587 </p> 588 589 <!-- Note: intentionally longer 80 columns --> 590 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 591 <dl> 592 <div> 593 <div> 594 </div> 595 </div> 596 </dl> 597 </div> 598 </div> 599 600 <!-- MIN_VERSION --> 601 <p> 602 This function was added in version <b><span></span></b>. 603 If you require this function, the manifest key 604 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 605 can ensure that your extension won't be run in an earlier browser version. 606 </p> 607 </div> <!-- /description --> 608 609 </div> <!-- /apiItem --> 610 611 </div> <!-- /apiGroup --> 612 613 <!-- EVENTS --> 614 <div id="eventsTemplate" class="apiGroup"> 615 <a></a> 616 <h3>Events</h3> 617 <!-- iterates over all events --> 618 <div class="apiItem"> 619 <a></a> 620 <h4>event name</h4> 621 622 <div class="summary"> 623 <!-- Note: intentionally longer 80 columns --> 624 <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>); 625 </div> 626 627 <div class="description"> 628 <p class="todo">Undocumented.</p> 629 <p> 630 A description from the json schema def of the event goes here. 631 </p> 632 633 <!-- PARAMETERS --> 634 <div> 635 <h4>Parameters</h4> 636 <dl> 637 <div> 638 <div> 639 </div> 640 </div> 641 </dl> 642 </div> 643 </div> <!-- /decription --> 644 645 </div> <!-- /apiItem --> 646 647 </div> <!-- /apiGroup --> 648 649 <!-- TYPES --> 650 <div class="apiGroup"> 651 <a name="types"></a> 652 <h3 id="types">Types</h3> 653 654 <!-- iterates over all types --> 655 <div class="apiItem"> 656 <a></a> 657 <h4>type name</h4> 658 659 <div> 660 </div> 661 662 </div> <!-- /apiItem --> 663 664 </div> <!-- /apiGroup --> 665 666 </div> <!-- /apiPage --> 667 </div> <!-- /gc-pagecontent --> 668 </div> <!-- /g-section --> 669 </div> <!-- /codesiteContent --> 670 <div id="gc-footer" --=""> 671 <div class="text"> 672 <p> 673 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 674 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 675 Attribution 3.0 License</a>, and code samples are licensed under the 676 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 677 </p> 678 <p> 679 ©2011 Google 680 </p> 681 682<!-- begin analytics --> 683<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 684<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 685 686<script type="text/javascript"> 687 // chrome doc tracking 688 try { 689 var engdocs = _gat._getTracker("YT-10763712-2"); 690 engdocs._trackPageview(); 691 } catch(err) {} 692 693 // code.google.com site-wide tracking 694 try { 695 _uacct="UA-18071-1"; 696 _uanchor=1; 697 _uff=0; 698 urchinTracker(); 699 } 700 catch(e) {/* urchinTracker not available. */} 701</script> 702<!-- end analytics --> 703 </div> 704 </div> <!-- /gc-footer --> 705 </div> <!-- /gc-container --> 706</body></html> 707
