Home | History | Annotate | Download | only in static 
      1 <div id="pageData-name" class="pageData">Override Pages</div>
      2 <div id="pageData-showTOC" class="pageData">true</div>
      3 
      4 <style>
      5 #pics {
      6   margin:2em 1em 1.5em;
      7 }
      8 
      9 #pics td {
     10   text-align:center;
     11   width:50%!important;
     12   border:none;
     13   padding:0 1em;
     14   font-size:90%;
     15 }
     16 
     17 #pics img {
     18   width:188;
     19   height:246;
     20   border:none;
     21 }
     22 </style>
     23 
     24 <p>
     25 Override pages are a way to substitute an HTML file from your extension
     26 for a page that Google Chrome normally provides.
     27 In addition to HTML,
     28 an override page usually has CSS and JavaScript code.
     29 </p>
     30 
     31 <p>
     32 An extension can replace any one of the following pages:
     33 <ul>
     34   <li> <b>Bookmark Manager:</b>
     35   The page that appears when the user chooses
     36   the Bookmark Manager menu item
     37   from the wrench menu or, on Mac,
     38   the Bookmark Manager item from the Bookmarks menu.
     39   You can also get to this page by entering the URL
     40   <b>chrome://bookmarks</b>.
     41   </li>
     42 
     43   <li> <b>History:</b>
     44   The page that appears when the user
     45   chooses the History menu item
     46   from the Tools (wrench) menu or, on Mac,
     47   the Show Full History item from the History menu.
     48   You can also get to this page by entering the URL
     49   <b>chrome://history</b>.
     50   </li>
     51 
     52   <li> <b>New Tab:</b>
     53   The page that appears when the user creates a new tab or window.
     54   You can also get to this page by entering the URL
     55   <b>chrome://newtab</b>.
     56   </li>
     57 </ul>
     58 </p>
     59 
     60 <p class="note">
     61 <b>Note:</b>
     62 A single extension can override
     63 <b>only one page</b>.
     64 For example, an extension can't override both
     65 the Bookmark Manager and History pages.
     66 </p>
     67 
     68 <p>
     69 Incognito windows are treated specially.
     70 New Tab pages cannot be overridden in incognito windows.
     71 Other override pages work in incognito windows
     72 as long as the
     73 <a href="manifest.html#incognito">incognito</a>
     74 manifest property is set to "spanning"
     75 (which is the default value for extensions
     76 but not for packaged apps).
     77 See <a href="overview.html#incognito">Saving data and incognito mode</a>
     78 in the Overview for more details on how you should treat
     79 incognito windows.
     80 </p>
     81 
     82 <p>
     83 The following screenshots show the default New Tab page
     84 next to a custom New Tab page.
     85 </p>
     86 
     87 <table id="pics">
     88   <tr>
     89     <td> <b>The default New Tab page</b> </td>
     90     <td> <b>An alternative New Tab page</b> </td>
     91   </tr>
     92   <tr>
     93     <td>
     94       <img src="images/ntp-default.png"
     95         alt="default New Tab page"
     96         width="200" height="173">
     97     </td>
     98     <td>
     99       <img src="images/ntp-blank.png"
    100         alt="a blank New Tab page"
    101         width="200" height="173">
    102     </td>
    103   </tr>
    104 </table>
    105 
    106 <h2 id="manifest">Manifest</h2>
    107 
    108 <p>
    109 Register an override page in the
    110 <a href="manifest.html">extension manifest</a> like this:
    111 </p>
    112 
    113 <pre>{
    114   "name": "My extension",
    115   ...
    116 
    117 <b>  "chrome_url_overrides" : {
    118     "<em>pageToOverride</em>": "<em>myPage.html</em>"
    119   }</b>,
    120   ...
    121 }</pre>
    122 
    123 <p>
    124 For <code><em>pageToOverride</em></code>, substitute one of the following:
    125 </p>
    126 
    127 <ul>
    128   <li> <code>bookmarks</code>
    129   <li> <code>history</code>
    130   <li> <code>newtab</code>
    131 </ul>
    132 
    133 
    134 <h2 id="tips">Tips</h2>
    135 
    136 <p>
    137 For an effective override page, follow these guidelines:
    138 </p>
    139 
    140 <ul>
    141   <li>
    142     <p>
    143     <b>Make your page quick and small.</b> <br />
    144     Users expect built-in browser pages to open instantly.
    145     Avoid doing things that might take a long time.
    146     For example, avoid synchronous fetches of network or database resources.
    147     </p>
    148   </li>
    149   <li>
    150     <p>
    151     <b>Include a title in your page.</b> <br />
    152     Otherwise people might see the URL of the page,
    153     which could be confusing.
    154     Here's an example of specifying the title:
    155     <code>&lt;title>New&nbsp;Tab&lt;/title></code>
    156     </p>
    157   </li>
    158   <li>
    159     <p>
    160     <b>Don't rely on the page having the keyboard focus.</b> <br />
    161     The address bar always gets the focus first
    162     when the user creates a new tab.
    163     </p>
    164   </li>
    165   <li>
    166     <p>
    167     <b>Don't try to emulate the default New Tab page.</b> <br />
    168     The APIs necessary to create
    169     a slightly modified version of the default New Tab page &mdash;
    170     with top pages,
    171     recently closed pages,
    172     tips,
    173     a theme background image,
    174     and so on &mdash;
    175     don't exist yet.
    176     Until they do,
    177     you're better off trying to make something completely different.
    178     </p>
    179   </li>
    180 </ul>
    181 
    182 <h2 id="examples"> Examples </h2>
    183 
    184 <p>
    185 See the
    186 <a href="samples.html#chrome_url_overrides">override samples</a>.
    187 </p>
    188