| OLD | NEW |
| 1 <p id="classSummary"> | 1 <p id="classSummary"> |
| 2 Use the <code>chrome.webNavigation</code> module to receive | 2 Use the <code>chrome.webNavigation</code> module to receive |
| 3 notifications about the status of navigations requests in-flight. | 3 notifications about the status of navigations requests in-flight. |
| 4 </p> | 4 </p> |
| 5 | 5 |
| 6 <h2>Manifest</h2> | 6 <h2 id="manifest">Manifest</h2> |
| 7 <p> | 7 <p> |
| 8 All <code>chrome.webNavigation</code> methods and events require you to declare | 8 All <code>chrome.webNavigation</code> methods and events require you to declare |
| 9 the "webNavigation" permission in the <a href="manifest.html">extension | 9 the "webNavigation" permission in the <a href="manifest.html">extension |
| 10 manifest</a>. | 10 manifest</a>. |
| 11 For example: | 11 For example: |
| 12 </p> | 12 </p> |
| 13 | 13 |
| 14 <pre>{ | 14 <pre>{ |
| 15 "name": "My extension", | 15 "name": "My extension", |
| 16 ... | 16 ... |
| 17 <b>"permissions": [ | 17 <b>"permissions": [ |
| 18 "webNavigation" | 18 "webNavigation" |
| 19 ]</b>, | 19 ]</b>, |
| 20 ... | 20 ... |
| 21 }</pre> | 21 }</pre> |
| 22 | 22 |
| 23 | 23 |
| 24 <h2>Examples</h2> | 24 <h2 id="examples">Examples</h2> |
| 25 | 25 |
| 26 <p> | 26 <p> |
| 27 You can find simple examples of using the tabs module in the | 27 You can find simple examples of using the tabs module in the |
| 28 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension
s/docs/examples/api/webNavigation/">examples/api/webNavigation</a> | 28 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension
s/docs/examples/api/webNavigation/">examples/api/webNavigation</a> |
| 29 directory. | 29 directory. |
| 30 For other examples and for help in viewing the source code, see | 30 For other examples and for help in viewing the source code, see |
| 31 <a href="samples.html">Samples</a>. | 31 <a href="samples.html">Samples</a>. |
| 32 </p> | 32 </p> |
| 33 | 33 |
| 34 <h2>Event order</h2> | 34 <h2 id="event_order">Event order</h2> |
| 35 <p> | 35 <p> |
| 36 For a navigation that is successfully completed, events are fired in the | 36 For a navigation that is successfully completed, events are fired in the |
| 37 following order: | 37 following order: |
| 38 <pre> | 38 <pre> |
| 39 onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted | 39 onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted |
| 40 </pre> | 40 </pre> |
| 41 </p> | 41 </p> |
| 42 <p> | 42 <p> |
| 43 Any error that occurs during the process results in an | 43 Any error that occurs during the process results in an |
| 44 <code>onErrorOccurred</code> event. For a specific navigation, there are no | 44 <code>onErrorOccurred</code> event. For a specific navigation, there are no |
| (...skipping 18 matching lines...) Expand all Loading... |
| 63 </p> | 63 </p> |
| 64 <p> | 64 <p> |
| 65 If a navigation was triggered via <a | 65 If a navigation was triggered via <a |
| 66 href="https://support.google.com/chrome/bin/answer.py?answer=177873">Chrome | 66 href="https://support.google.com/chrome/bin/answer.py?answer=177873">Chrome |
| 67 Instant</a> or <a | 67 Instant</a> or <a |
| 68 href="https://support.google.com/chrome/bin/answer.py?answer=1385029">Instant | 68 href="https://support.google.com/chrome/bin/answer.py?answer=1385029">Instant |
| 69 Pages</a>, a completely loaded page is swapped into the current tab. In that | 69 Pages</a>, a completely loaded page is swapped into the current tab. In that |
| 70 case, an <code>onTabReplaced</code> event is fired. | 70 case, an <code>onTabReplaced</code> event is fired. |
| 71 </p> | 71 </p> |
| 72 | 72 |
| 73 <h2>Relation to webRequest events</h2> | 73 <h2 id="relation_to_webRequest">Relation to webRequest events</h2> |
| 74 <p> | 74 <p> |
| 75 There is no defined ordering between events of the <a | 75 There is no defined ordering between events of the <a |
| 76 href="webRequest.html">webRequest API</a> and the events of the | 76 href="webRequest.html">webRequest API</a> and the events of the |
| 77 webNavigation API. It is possible that webRequest events are still received for | 77 webNavigation API. It is possible that webRequest events are still received for |
| 78 frames that already started a new navigation, or that a navigation only | 78 frames that already started a new navigation, or that a navigation only |
| 79 proceeds after the network resources are already fully loaded. | 79 proceeds after the network resources are already fully loaded. |
| 80 </p> | 80 </p> |
| 81 <p> | 81 <p> |
| 82 In general, the webNavigation events are closely related to the navigation | 82 In general, the webNavigation events are closely related to the navigation |
| 83 state that is displayed in the UI, while the webRequest events correspond to | 83 state that is displayed in the UI, while the webRequest events correspond to |
| 84 the state of the network stack which is generally opaque to the user. | 84 the state of the network stack which is generally opaque to the user. |
| 85 </p> | 85 </p> |
| 86 | 86 |
| 87 <h2>A note about tab IDs</h2> | 87 <h2 id="tab_ids">A note about tab IDs</h2> |
| 88 <p> | 88 <p> |
| 89 Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab | 89 Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab |
| 90 that is being pre-rendered. Such tabs are not accessible via the | 90 that is being pre-rendered. Such tabs are not accessible via the |
| 91 <a href="tabs.html">tabs API</a> nor can you request information about them via | 91 <a href="tabs.html">tabs API</a> nor can you request information about them via |
| 92 <code>webNavigation.getFrame</code> or <code>webNavigation.getAllFrames</code>. | 92 <code>webNavigation.getFrame</code> or <code>webNavigation.getAllFrames</code>. |
| 93 Once such a tab is swapped in, an <code>onTabReplaced</code> event is fired and | 93 Once such a tab is swapped in, an <code>onTabReplaced</code> event is fired and |
| 94 they become accessible via these APIs. | 94 they become accessible via these APIs. |
| 95 </p> | 95 </p> |
| 96 | 96 |
| 97 <h2>A note about timestamps</h2> | 97 <h2 id="timestamps">A note about timestamps</h2> |
| 98 <p> | 98 <p> |
| 99 It's important to note that some technical oddities in the OS's handling | 99 It's important to note that some technical oddities in the OS's handling |
| 100 of distinct Chrome processes can cause the clock to be skewed between the | 100 of distinct Chrome processes can cause the clock to be skewed between the |
| 101 browser itself and extension processes. That means that WebNavigation's events' | 101 browser itself and extension processes. That means that WebNavigation's events' |
| 102 <code>timeStamp</code> property is only guaranteed to be <i>internally</i> | 102 <code>timeStamp</code> property is only guaranteed to be <i>internally</i> |
| 103 consistent. Comparing one event to another event will give you the correct | 103 consistent. Comparing one event to another event will give you the correct |
| 104 offset between them, but comparing them to the current time inside the | 104 offset between them, but comparing them to the current time inside the |
| 105 extension (via <code>(new Date()).getTime()</code>, for instance) might give | 105 extension (via <code>(new Date()).getTime()</code>, for instance) might give |
| 106 unexpected results. | 106 unexpected results. |
| 107 </p> | 107 </p> |
| 108 | 108 |
| 109 <h2>A note about frame and process IDs</h2> | 109 <h2 id="frame_ids">A note about frame and process IDs</h2> |
| 110 <p> | 110 <p> |
| 111 Due to the multi-process nature of Chrome, a tab might use different processes | 111 Due to the multi-process nature of Chrome, a tab might use different processes |
| 112 to render the source and destination of a web page. Therefore, if a navigation | 112 to render the source and destination of a web page. Therefore, if a navigation |
| 113 takes place in a new process, you might receive events both from the new and | 113 takes place in a new process, you might receive events both from the new and |
| 114 the old page until the new navigation is committed (i.e. the | 114 the old page until the new navigation is committed (i.e. the |
| 115 <code>onCommitted</code> event is send for the new main frame). Because frame | 115 <code>onCommitted</code> event is send for the new main frame). Because frame |
| 116 IDs are only unique for a given process, the webNavigation events include a | 116 IDs are only unique for a given process, the webNavigation events include a |
| 117 process ID, so you can still determine which frame a navigation came from. | 117 process ID, so you can still determine which frame a navigation came from. |
| 118 </p> | 118 </p> |
| 119 <p> | 119 <p> |
| 120 Also note that during a provisional load the process might be switched several | 120 Also note that during a provisional load the process might be switched several |
| 121 times. This happens when the load is redirected to a different site. In this | 121 times. This happens when the load is redirected to a different site. In this |
| 122 case, you will receive repeated <code>onBeforeNavigate</code> and | 122 case, you will receive repeated <code>onBeforeNavigate</code> and |
| 123 <code>onErrorOccurred</code> events, until you receive the final | 123 <code>onErrorOccurred</code> events, until you receive the final |
| 124 <code>onCommitted</code> event. | 124 <code>onCommitted</code> event. |
| 125 </p> | 125 </p> |
| 126 | 126 |
| 127 <h2>Transition types and qualifiers</h2> | 127 <h2 id="transition_types">Transition types and qualifiers</h2> |
| 128 <p> | 128 <p> |
| 129 The webNavigation API's <code>onCommitted</code> event has a | 129 The webNavigation API's <code>onCommitted</code> event has a |
| 130 <code>transitionType</code> and a <code>transitionQualifiers</code> property. | 130 <code>transitionType</code> and a <code>transitionQualifiers</code> property. |
| 131 The <em>transition type</em> is the same as used in the <a | 131 The <em>transition type</em> is the same as used in the <a |
| 132 href="history.html#transition_types">history API</a> describing how the browser | 132 href="history.html#transition_types">history API</a> describing how the browser |
| 133 navigated to this particular URL. In addition, several <em>transition | 133 navigated to this particular URL. In addition, several <em>transition |
| 134 qualifiers</em> can be returned that further define the navigation. | 134 qualifiers</em> can be returned that further define the navigation. |
| 135 </p> | 135 </p> |
| 136 <p> | 136 <p> |
| 137 The following transition qualifiers exist: | 137 The following transition qualifiers exist: |
| (...skipping 21 matching lines...) Expand all Loading... |
| 159 <td> | 159 <td> |
| 160 The user used the Forward or Back button to initiate the navigation. | 160 The user used the Forward or Back button to initiate the navigation. |
| 161 </td> | 161 </td> |
| 162 </tr> | 162 </tr> |
| 163 <tr> | 163 <tr> |
| 164 <td>"from_address_bar"</td> | 164 <td>"from_address_bar"</td> |
| 165 <td> | 165 <td> |
| 166 The user initiated the navigation from the address bar (aka Omnibox). | 166 The user initiated the navigation from the address bar (aka Omnibox). |
| 167 </td> | 167 </td> |
| 168 </tr> | 168 </tr> |
| 169 </table> | 169 </table> |
| OLD | NEW |