src/chrome/common/extensions/docs/templates/intros/history.html

   1 <h2 id="manifest">Manifest</h2>
   2
   3 <p>You must declare the "history" permission
   4 in the <a href="manifest.html">extension manifest</a>
   5 to use the history API.
   6 For example:</p>
   7 <pre data-filename="manifest.json">
   8 {
   9   "name": "My extension",
  10   ...
  11   <b>"permissions": [
  12     "history"
  13   ]</b>,
  14   ...
  15 }
  16 </pre>
  17
  18 <h2 id="transition_types">Transition types</h2>
  19
  20 <p>
  21 The history API uses a <em>transition type</em> to describe
  22 how the browser navigated to a particular URL
  23 on a particular visit.
  24 For example, if a user visits a page
  25 by clicking a link on another page,
  26 the transition type is "link".
  27 </p>
  28
  29 <p>
  30 The following table describes each transition type.
  31 </p>
  32
  33 <table>
  34 <tr>
  35   <th> Transition type </th> <th> Description </th>
  36 </tr>
  37 <tr id="tt_link">
  38   <td>"link"</td>
  39   <td>
  40     The user got to this page by clicking a link on another page.
  41   </td>
  42 </tr>
  43 <tr id="tt_typed">
  44   <td>"typed"</td>
  45   <td>
  46     The user got this page by typing the URL in the address bar.
  47     Also used for other explicit navigation actions.
  48     See also <a href="#tt_generated">generated</a>,
  49     which is used for cases where the user selected a choice
  50     that didn't look at all like a URL.
  51   </td>
  52 </tr>
  53 <tr id="tt_auto_bookmark">
  54   <td>"auto_bookmark"</td>
  55   <td>
  56     The user got to this page through a suggestion in the UI &mdash;
  57     for example, through a menu item.
  58   </td>
  59 </tr>
  60 <tr id="tt_auto_subframe">
  61   <td>"auto_subframe"</td>
  62   <td>
  63     Subframe navigation.
  64     This is any content that is automatically
  65     loaded in a non-top-level frame.
  66     For example, if a page consists of
  67     several frames containing ads,
  68     those ad URLs have this transition type.
  69     The user may not even realize the content in these pages
  70     is a separate frame, and so may not care about the URL
  71     (see also <a href="#tt_manual_subframe">manual_subframe</a>).
  72   </td>
  73 </tr>
  74 <tr id="tt_manual_subframe">
  75   <td>"manual_subframe"</td>
  76   <td>
  77     For subframe navigations that are explicitly requested by the user
  78     and generate new navigation entries in the back/forward list.
  79     An explicitly requested frame is probably more important than
  80     an automatically loaded frame
  81     because the user probably cares about the fact that
  82     the requested frame was loaded.
  83   </td>
  84 </tr>
  85 <tr id="tt_generated">
  86   <td>"generated"</td>
  87   <td>
  88     The user got to this page by typing in the address bar
  89     and selecting an entry that did not look like a URL.
  90     For example, a match might have the URL of a Google search result page,
  91     but it might appear to the user as "Search Google for ...".
  92     These are not quite the same as <a href="#tt_typed">typed</a> navigations
  93     because the user didn't type or see the destination URL.
  94     See also <a href="#tt_keyword">keyword</a>.
  95   </td>
  96 </tr>
  97 <tr id="tt_auto_toplevel">
  98   <td>"auto_toplevel"</td>
  99   <td>
 100     The page was specified in the command line or is the start page.
 101   </td>
 102 </tr>
 103 <tr id="tt_form_submit">
 104   <td>"form_submit"</td>
 105   <td>
 106     The user filled out values in a form and submitted it.
 107     Note that in some situations &mdash;
 108     such as when a form uses script to submit contents &mdash;
 109     submitting a form does not result in this transition type.
 110   </td>
 111 </tr>
 112 <tr id="tt_reload">
 113   <td>"reload"</td>
 114   <td>
 115     The user reloaded the page,
 116     either by clicking the reload button
 117     or by pressing Enter in the address bar.
 118     Session restore and Reopen closed tab use this transition type, too.
 119   </td>
 120 </tr>
 121 <tr id="tt_keyword">
 122   <td>"keyword"</td>
 123   <td>
 124     The URL was generated from a replaceable keyword
 125     other than the default search provider.
 126     See also
 127     <a href="#tt_keyword_generated">keyword_generated</a>.
 128   </td>
 129 </tr>
 130 <tr id="tt_keyword_generated">
 131   <td>"keyword_generated"</td>
 132   <td>
 133     Corresponds to a visit generated for a keyword.
 134     See also <a href="#tt_keyword">keyword</a>.
 135   </td>
 136 </tr>
 137 </table>
 138
 139 <h2 id="examples">Examples</h2>
 140
 141 <p>
 142 For examples of using this API, see the
 143 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/history/">history sample directory</a> and the
 144 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/test/data/extensions/api_test/history/">history API test directory</a>.
 145 For other examples and for help in viewing the source code, see
 146 <a href="samples.html">Samples</a>.
 147 </p>