| OLD | NEW |
|---|
| (Empty) | |
| 1 <!-- BEGIN AUTHORED CONTENT --> |
| 2 <p id="classSummary"> |
| 3 Use the <code>chrome.webNavigation</code> module to receive |
| 4 notifications about the status of navigations requests in-flight. |
| 5 </p> |
| 6 <h2>Manifest</h2> |
| 7 <p> |
| 8 All <code>chrome.webNavigation</code> methods and events require you to declare |
| 9 the "webNavigation" permission in the <a href="manifest.html">extension |
| 10 manifest</a>. |
| 11 For example: |
| 12 </p> |
| 13 <pre>{ |
| 14 "name": "My extension", |
| 15 ... |
| 16 <b>"permissions": [ |
| 17 "webNavigation" |
| 18 ]</b>, |
| 19 ... |
| 20 }</pre> |
| 21 <h2>Examples</h2> |
| 22 <p> |
| 23 You can find simple examples of using the tabs module in the |
| 24 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension
s/docs/examples/api/webNavigation/">examples/api/webNavigation</a> |
| 25 directory. |
| 26 For other examples and for help in viewing the source code, see |
| 27 <a href="samples.html">Samples</a>. |
| 28 </p> |
| 29 <h2>Event order</h2> |
| 30 <p> |
| 31 For a navigation that is successfully completed, events are fired in the |
| 32 following order: |
| 33 <pre> |
| 34 onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted |
| 35 </pre> |
| 36 </p> |
| 37 <p> |
| 38 Any error that occurs during the process results in an |
| 39 <code>onErrorOccurred</code> event. For a specific navigation, there are no |
| 40 further events fired after <code>onErrorOccurred</code>. |
| 41 </p> |
| 42 <p> |
| 43 If a navigating frame contains subframes, its <code>onCommitted</code> is fired |
| 44 before any of its children's <code>onBeforeNavigate</code>; while |
| 45 <code>onCompleted</code> is fired after all of its children's |
| 46 <code>onCompleted</code>. |
| 47 </p> |
| 48 <p> |
| 49 If the reference fragment of a frame is changed, a |
| 50 <code>onReferenceFragmentUpdated</code> event is fired. This event can fire any |
| 51 time after <code>onDOMContentLoaded</code>, even after |
| 52 <code>onCompleted</code>. |
| 53 </p> |
| 54 <h2>Relation to webRequest events</h2> |
| 55 <p> |
| 56 There is no defined ordering between events of the <a |
| 57 href="webRequest.html">webRequest API</a> and the events of the |
| 58 webNavigation API. It is possible that webRequest events are still received for |
| 59 frames that already started a new navigation, or that a navigation only |
| 60 proceeds after the network resources are already fully loaded. |
| 61 </p> |
| 62 <p> |
| 63 In general, the webNavigation events are closely related to the navigation |
| 64 state that is displayed in the UI, while the webRequest events correspond to |
| 65 the state of the network stack which is generally opaque to the user. |
| 66 </p> |
| 67 <h2>A note about timestamps</h2> |
| 68 <p> |
| 69 It's important to note that some technical oddities in the OS's handling |
| 70 of distinct Chrome processes can cause the clock to be skewed between the |
| 71 browser itself and extension processes. That means that WebNavigation's events' |
| 72 <code>timeStamp</code> property is only guaranteed to be <i>internally</i> |
| 73 consistent. Comparing one event to another event will give you the correct |
| 74 offset between them, but comparing them to the current time inside the |
| 75 extension (via <code>(new Date()).getTime()</code>, for instance) might give |
| 76 unexpected results. |
| 77 </p> |
| 78 <h2>Transition types and qualifiers</h2> |
| 79 <p> |
| 80 The webNavigation API's <code>onCommitted</code> event has a |
| 81 <code>transitionType</code> and a <code>transitionQualifiers</code> property. |
| 82 The <em>transition type</em> is the same as used in the <a |
| 83 href="history.html#transition_types">history API</a> describing how the browser |
| 84 navigated to this particular URL. In addition, several <em>transition |
| 85 qualifiers</em> can be returned that further define the navigation. |
| 86 </p> |
| 87 <p> |
| 88 The following transition qualifiers exist: |
| 89 </p> |
| 90 <table> |
| 91 <tr> |
| 92 <th> Transition qualifier </th> <th> Description </th> |
| 93 </tr> |
| 94 <tr> |
| 95 <td>"client_redirect"</td> |
| 96 <td> |
| 97 One or more redirects caused by JavaScript or meta refresh tags on the page |
| 98 happened during the navigation. |
| 99 </td> |
| 100 </tr> |
| 101 <tr> |
| 102 <td>"server_redirect"</td> |
| 103 <td> |
| 104 One or more redirects caused by HTTP headers sent from the server happened |
| 105 during the navigation. |
| 106 </td> |
| 107 </tr> |
| 108 <tr> |
| 109 <td>"forward_back"</td> |
| 110 <td> |
| 111 The user used the Forward or Back button to initiate the navigation. |
| 112 </td> |
| 113 </tr> |
| 114 <tr> |
| 115 <td>"from_address_bar"</td> |
| 116 <td> |
| 117 The user initiated the navigation from the address bar (aka Omnibox). |
| 118 </td> |
| 119 </tr> |
| 120 </table> |
| 121 <!-- END AUTHORED CONTENT --> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10700118:
Extensions Docs Server: First doc conversions (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src