override.html revision 8ae428e0fb7feea16d79853f29447469a93bedff
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>Override - 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 class="leftNavSelected">Override Pages</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="tabs.html">Tabs</a></li> 181 <li><a href="windows.html">Windows</a></li> 182 </ul> 183 </li> 184 <li>Implementation 185 <ul> 186 <li><a href="a11y.html">Accessibility</a></li> 187 <li><a href="background_pages.html">Background Pages</a></li> 188 <li><a href="content_scripts.html">Content Scripts</a></li> 189 <li><a href="xhr.html">Cross-Origin XHR</a></li> 190 <li><a href="idle.html">Idle</a></li> 191 <li><a href="i18n.html">Internationalization</a></li> 192 <li><a href="messaging.html">Message Passing</a></li> 193 <li><a href="npapi.html">NPAPI Plugins</a></li> 194 </ul> 195 </li> 196 <li>Finishing 197 <ul> 198 <li><a href="hosting.html">Hosting</a></li> 199 <li><a href="external_extensions.html">Other Deployment Options</a></li> 200 </ul> 201 </li> 202 </ul> 203 </li> 204 <li><h2><a href="tutorials.html">Tutorials</a></h2> 205 <ul> 206 <li><a href="tut_debugging.html">Debugging</a></li> 207 <li><a href="tut_analytics.html">Google Analytics</a></li> 208 <li><a href="tut_oauth.html">OAuth</a></li> 209 </ul> 210 </li> 211 <li><h2>Reference</h2> 212 <ul> 213 <li>Formats 214 <ul> 215 <li><a href="manifest.html">Manifest Files</a></li> 216 <li><a href="match_patterns.html">Match Patterns</a></li> 217 <!-- <li>Packages (.crx)</li> --> 218 </ul> 219 </li> 220 <li><a href="api_index.html">chrome.* APIs</a></li> 221 <li><a href="api_other.html">Other APIs</a></li> 222 </ul> 223 </li> 224 <li><h2><a href="samples.html">Samples</a></h2></li> 225 </ul> 226 </div> 227 228 <div class="g-unit" id="gc-pagecontent"> 229 <div id="pageTitle"> 230 <h1 class="page_title">Override</h1> 231 </div> 232 <!-- TABLE OF CONTENTS --> 233 <div id="toc"> 234 <h2>Contents</h2> 235 <ol> 236 <li> 237 <a href="#manifest">Manifest</a> 238 <ol> 239 <li style="display: none; "> 240 <a>h3Name</a> 241 </li> 242 </ol> 243 </li><li> 244 <a href="#tips">Tips</a> 245 <ol> 246 <li style="display: none; "> 247 <a>h3Name</a> 248 </li> 249 </ol> 250 </li><li> 251 <a href="#examples"> Examples </a> 252 <ol> 253 <li style="display: none; "> 254 <a>h3Name</a> 255 </li> 256 </ol> 257 </li> 258 <li style="display: none; "> 259 <a href="#apiReference">API reference</a> 260 <ol> 261 <li> 262 <a href="#properties">Properties</a> 263 <ol> 264 <li> 265 <a href="#property-anchor">propertyName</a> 266 </li> 267 </ol> 268 </li> 269 <li> 270 <a href="#methods">Methods</a> 271 <ol> 272 <li> 273 <a href="#method-anchor">methodName</a> 274 </li> 275 </ol> 276 </li> 277 <li> 278 <a href="#events">Events</a> 279 <ol> 280 <li> 281 <a href="#event-anchor">eventName</a> 282 </li> 283 </ol> 284 </li> 285 <li> 286 <a href="#types">Types</a> 287 <ol> 288 <li> 289 <a href="#id-anchor">id</a> 290 </li> 291 </ol> 292 </li> 293 </ol> 294 </li> 295 </ol> 296 </div> 297 <!-- /TABLE OF CONTENTS --> 298 299 <!-- Standard content lead-in for experimental API pages --> 300 <p id="classSummary" style="display: none; "> 301 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 302 </p> 303 304 <!-- STATIC CONTENT PLACEHOLDER --> 305 <div id="static"><style> 306#pics { 307 margin:2em 1em 1.5em; 308} 309 310#pics td { 311 text-align:center; 312 width:50%!important; 313 border:none; 314 padding:0 1em; 315 font-size:90%; 316} 317 318#pics img { 319 width:188; 320 height:246; 321 border:none; 322} 323</style> 324 325<div id="pageData-title" class="pageData">Override Pages</div> 326<div id="pageData-showTOC" class="pageData">true</div> 327 328<p> 329Override pages are a way to substitute an HTML file from your extension 330for a page that Google Chrome normally provides. 331In addition to HTML, 332an override page usually has CSS and JavaScript code. 333</p> 334 335<p> 336An extension can replace any one of the following pages: 337</p><ul> 338 <li> <b>Bookmark Manager:</b> 339 The page that appears when the user chooses 340 the Bookmark Manager menu item 341 from the Tools (wrench) menu or, on Mac, 342 the Bookmark Manager item from the Bookmarks menu. 343 You can also get to this page by entering the URL 344 <b>chrome://bookmarks</b>. 345 </li> 346 347 <li> <b>History:</b> 348 The page that appears when the user 349 chooses the History menu item 350 from the Tools (wrench) menu or, on Mac, 351 the Show Full History item from the History menu. 352 You can also get to this page by entering the URL 353 <b>chrome://history</b>. 354 </li> 355 356 <li> <b>New Tab:</b> 357 The page that appears when the user creates a new tab or window. 358 You can also get to this page by entering the URL 359 <b>chrome://newtab</b>. 360 </li> 361</ul> 362<p></p> 363 364<p class="note"> 365<b>Note:</b> 366A single extension can override 367only one page. 368</p> 369 370<p class="note"> 371<b>Note:</b> 372If you want to override the page in incognito windows as well, make sure to 373specify "spanning" mode for the <a href="manifest.html#incognito">incognito</a> 374manifest property. 375</p> 376 377<p> 378The following screenshots show the default New Tab page 379next to a custom New Tab page. 380</p> 381 382<table id="pics"> 383 <tbody><tr> 384 <td> <b>The default New Tab page</b> </td> 385 <td> <b>An alternative New Tab page</b> </td> 386 </tr> 387 <tr> 388 <td> 389 <img src="images/ntp-default.png" alt="default New Tab page" width="200" height="173"> 390 </td> 391 <td> 392 <img src="images/ntp-blank.png" alt="a blank New Tab page" width="200" height="173"> 393 </td> 394 </tr> 395</tbody></table> 396 397<h2 id="manifest">Manifest</h2> 398 399<p> 400Register an override page in the 401<a href="manifest.html">extension manifest</a> like this: 402</p> 403 404<pre>{ 405 "name": "My extension", 406 ... 407 408<b> "chrome_url_overrides" : { 409 "<em>pageToOverride</em>": "<em>myPage.html</em>" 410 }</b>, 411 ... 412}</pre> 413 414<p> 415For <code><em>pageToOverride</em></code>, substitute one of the following: 416</p> 417 418<ul> 419 <li> <code>bookmarks</code> 420 </li><li> <code>history</code> 421 </li><li> <code>newtab</code> 422</li></ul> 423 424 425<h2 id="tips">Tips</h2> 426 427<p> 428For an effective override page, follow these guidelines: 429</p> 430 431<ul> 432 <li> 433 <p> 434 <b>Make your page quick and small.</b> <br> 435 Users expect built-in browser pages to open instantly. 436 Avoid doing things that might take a long time. 437 For example, avoid synchronous fetches of network or database resources. 438 </p> 439 </li> 440 <li> 441 <p> 442 <b>Include a title in your page.</b> <br> 443 Otherwise people might see the URL of the page, 444 which could be confusing. 445 Here's an example of specifying the title: 446 <code><title>New Tab</title></code> 447 </p> 448 </li> 449 <li> 450 <p> 451 <b>Don't rely on the page having the keyboard focus.</b> <br> 452 The address bar always gets the focus first 453 when the user creates a new tab. 454 </p> 455 </li> 456 <li> 457 <p> 458 <b>Don't try to emulate the default New Tab page.</b> <br> 459 The APIs necessary to create 460 a slightly modified version of the default New Tab page — 461 with top pages, 462 recently closed pages, 463 tips, 464 a theme background image, 465 and so on — 466 don't exist yet. 467 Until they do, 468 you're better off trying to make something completely different. 469 </p> 470 </li> 471</ul> 472 473<h2 id="examples"> Examples </h2> 474 475<p> 476You can find simple examples of defining override pages in the 477<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/override/">examples/api/override</a> 478directory. 479For other examples and for help in viewing the source code, see 480<a href="samples.html">Samples</a>. 481</p> 482 483 484<!-- [PENDING: Maybe have a gallery of NTPs?] --> 485</div> 486 487 <!-- API PAGE --> 488 <div class="apiPage" style="display: none; "> 489 <a name="apiReference"></a> 490 <h2>API reference: chrome.apiname </h2> 491 492 <!-- PROPERTIES --> 493 <div class="apiGroup"> 494 <a name="properties"></a> 495 <h3 id="properties">Properties</h3> 496 497 <div> 498 <a></a> 499 <h4>getLastError</h4> 500 <div class="summary"> 501 <!-- Note: intentionally longer 80 columns --> 502 <span>chrome.extension</span><span>lastError</span> 503 </div> 504 <div> 505 </div> 506 </div> 507 508 </div> <!-- /apiGroup --> 509 510 <!-- METHODS --> 511 <div class="apiGroup" id="methods"> 512 <a name="methods"></a> 513 <h3>Methods</h3> 514 515 <!-- iterates over all functions --> 516 <div class="apiItem"> 517 <a></a> <!-- method-anchor --> 518 <h4>method name</h4> 519 520 <div class="summary"><span>void</span> 521 <!-- Note: intentionally longer 80 columns --> 522 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 523 <var><span></span></var></span>)</div> 524 525 <div class="description"> 526 <p class="todo">Undocumented.</p> 527 <p> 528 A description from the json schema def of the function goes here. 529 </p> 530 531 <!-- PARAMETERS --> 532 <h4>Parameters</h4> 533 <dl> 534 <div> 535 <div> 536 </div> 537 </div> 538 </dl> 539 540 <!-- RETURNS --> 541 <h4>Returns</h4> 542 <dl> 543 <div> 544 <div> 545 </div> 546 </div> 547 </dl> 548 549 <!-- CALLBACK --> 550 <div> 551 <div> 552 <h4>Callback function</h4> 553 <p> 554 The callback <em>parameter</em> should specify a function 555 that looks like this: 556 </p> 557 <p> 558 If you specify the <em>callback</em> parameter, it should 559 specify a function that looks like this: 560 </p> 561 562 <!-- Note: intentionally longer 80 columns --> 563 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 564 <dl> 565 <div> 566 <div> 567 </div> 568 </div> 569 </dl> 570 </div> 571 </div> 572 573 <!-- MIN_VERSION --> 574 <p> 575 This function was added in version <b><span></span></b>. 576 If you require this function, the manifest key 577 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 578 can ensure that your extension won't be run in an earlier browser version. 579 </p> 580 </div> <!-- /description --> 581 582 </div> <!-- /apiItem --> 583 584 </div> <!-- /apiGroup --> 585 586 <!-- EVENTS --> 587 <div class="apiGroup"> 588 <a name="events"></a> 589 <h3 id="events">Events</h3> 590 591 <!-- iterates over all events --> 592 <div class="apiItem"> 593 <a></a> 594 <h4>event name</h4> 595 596 <div class="summary"> 597 <!-- Note: intentionally longer 80 columns --> 598 <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>); 599 </div> 600 601 <div class="description"> 602 <p class="todo">Undocumented.</p> 603 <p> 604 A description from the json schema def of the event goes here. 605 </p> 606 607 <!-- PARAMETERS --> 608 <h4>Parameters</h4> 609 <dl> 610 <div> 611 <div> 612 </div> 613 </div> 614 </dl> 615 616 </div> <!-- /decription --> 617 618 </div> <!-- /apiItem --> 619 620 </div> <!-- /apiGroup --> 621 622 <!-- TYPES --> 623 <div class="apiGroup"> 624 <a name="types"></a> 625 <h3 id="types">Types</h3> 626 627 <!-- iterates over all types --> 628 <div class="apiItem"> 629 <a></a> 630 <h4>type name</h4> 631 632 <div> 633 </div> 634 635 </div> <!-- /apiItem --> 636 637 </div> <!-- /apiGroup --> 638 639 </div> <!-- /apiPage --> 640 </div> <!-- /gc-pagecontent --> 641 </div> <!-- /g-section --> 642 </div> <!-- /codesiteContent --> 643 <div id="gc-footer" --=""> 644 <div class="text"> 645 <p> 646 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 647 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 648 Attribution 3.0 License</a>, and code samples are licensed under the 649 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 650 </p> 651 <p> 652 ©2010 Google 653 </p> 654 655<!-- begin analytics --> 656<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 657<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 658 659<script type="text/javascript"> 660 // chrome doc tracking 661 try { 662 var engdocs = _gat._getTracker("YT-10763712-2"); 663 engdocs._trackPageview(); 664 } catch(err) {} 665 666 // code.google.com site-wide tracking 667 try { 668 _uacct="UA-18071-1"; 669 _uanchor=1; 670 _uff=0; 671 urchinTracker(); 672 } 673 catch(e) {/* urchinTracker not available. */} 674</script> 675<!-- end analytics --> 676 </div> 677 </div> <!-- /gc-footer --> 678 </div> <!-- /gc-container --> 679</body></html> 680
