chrome/common/extensions/docs/templates/articles/override.html

   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">incognito</a>
  74 manifest property is set to "spanning"
  75 (which is the default value).
  76 See <a href="overview#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">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 <!-- TODO(vasilii): Fix broken link. -->
 186 <a href="samples#search:chrome_url_overrides">override samples</a>.
 187 </p>