Home | History | Annotate | Download | only in articles 
      1 <h1>Override Pages</h1>
      2 
      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 Chrome 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 Chrome 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/incognito.html">incognito</a>
     74 manifest property is set to "spanning"
     75 (which is the default value).
     76 See <a href="overview.html#incognito">Saving data and incognito mode</a>
     77 in the Overview for more details on how you should treat
     78 incognito windows.
     79 </p>
     80 
     81 <p>
     82 The following screenshots show the default New Tab page
     83 next to a custom New Tab page.
     84 </p>
     85 
     86 <table id="pics">
     87   <tr>
     88     <td> <b>The default New Tab page</b> </td>
     89     <td> <b>An alternative New Tab page</b> </td>
     90   </tr>
     91   <tr>
     92     <td>
     93       <img src="{{static}}/images/ntp-default.png"
     94         alt="default New Tab page"
     95         width="200" height="173">
     96     </td>
     97     <td>
     98       <img src="{{static}}/images/ntp-blank.png"
     99         alt="a blank New Tab page"
    100         width="200" height="173">
    101     </td>
    102   </tr>
    103 </table>
    104 
    105 <h2 id="manifest">Manifest</h2>
    106 
    107 <p>
    108 Register an override page in the
    109 <a href="manifest.html">extension manifest</a> like this:
    110 </p>
    111 
    112 <pre>{
    113   "name": "My extension",
    114   ...
    115 
    116 <b>  "chrome_url_overrides" : {
    117     "<em>pageToOverride</em>": "<em>myPage.html</em>"
    118   }</b>,
    119   ...
    120 }</pre>
    121 
    122 <p>
    123 For <code><em>pageToOverride</em></code>, substitute one of the following:
    124 </p>
    125 
    126 <ul>
    127   <li> <code>bookmarks</code>
    128   <li> <code>history</code>
    129   <li> <code>newtab</code>
    130 </ul>
    131 
    132 
    133 <h2 id="tips">Tips</h2>
    134 
    135 <p>
    136 For an effective override page, follow these guidelines:
    137 </p>
    138 
    139 <ul>
    140   <li>
    141     <p>
    142     <b>Make your page quick and small.</b> <br />
    143     Users expect built-in browser pages to open instantly.
    144     Avoid doing things that might take a long time.
    145     For example, avoid synchronous fetches of network or database resources.
    146     </p>
    147   </li>
    148   <li>
    149     <p>
    150     <b>Include a title in your page.</b> <br />
    151     Otherwise people might see the URL of the page,
    152     which could be confusing.
    153     Here's an example of specifying the title:
    154     <code>&lt;title>New&nbsp;Tab&lt;/title></code>
    155     </p>
    156   </li>
    157   <li>
    158     <p>
    159     <b>Don't rely on the page having the keyboard focus.</b> <br />
    160     The address bar always gets the focus first
    161     when the user creates a new tab.
    162     </p>
    163   </li>
    164   <li>
    165     <p>
    166     <b>Don't try to emulate the default New Tab page.</b> <br />
    167     The APIs necessary to create
    168     a slightly modified version of the default New Tab page &mdash;
    169     with top pages,
    170     recently closed pages,
    171     tips,
    172     a theme background image,
    173     and so on &mdash;
    174     don't exist yet.
    175     Until they do,
    176     you're better off trying to make something completely different.
    177     </p>
    178   </li>
    179 </ul>
    180 
    181 <h2 id="examples"> Examples </h2>
    182 
    183 <p>
    184 See the
    185 <a href="samples.html#chrome_url_overrides">override samples</a>.
    186 </p>
    187