Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(489)

Side by Side Diff: chrome/common/extensions/docs/server2/templates/intros/declarativeWebRequest.html

Issue 10832042: Extensions Docs Server: Doc conversion script (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src
Patch Set: everything but svn stuff Created 8 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
1 <!-- BEGIN AUTHORED CONTENT -->
2 <h2 id="notes">Notes</h2> 1 <h2 id="notes">Notes</h2>
2
3 <p> 3 <p>
4 Use the <code>chrome.declarativeWebRequest</code> module to intercept, block, or 4 Use the <code>chrome.declarativeWebRequest</code> module to intercept, block, or
5 modify requests in-flight. It is significantly faster than the <a 5 modify requests in-flight. It is significantly faster than the <a
6 href="webRequest.html"><code>chrome.webRequest</code> API</a> because you can 6 href="webRequest.html"><code>chrome.webRequest</code> API</a> because you can
7 register rules that are evaluated in the browser rather than the 7 register rules that are evaluated in the browser rather than the
8 JavaScript engine which reduces roundtrip latencies and allows for very high 8 JavaScript engine which reduces roundtrip latencies and allows for very high
9 efficiency. 9 efficiency.
10 </p> 10 </p>
11
11 <h2 id="manifest">Manifest</h2> 12 <h2 id="manifest">Manifest</h2>
13
12 <p> 14 <p>
13 You must declare the "declarative" and the "declarativeWebRequest" permission in 15 You must declare the "declarative" and the "declarativeWebRequest" permission in
14 the <a href="manifest.html">extension manifest</a> to use this API, 16 the <a href="manifest.html">extension manifest</a> to use this API,
15 along with <a href="manifest.html#permissions">host permissions</a> for any 17 along with <a href="manifest.html#permissions">host permissions</a> for any
16 hosts whose network requests you want to access. 18 hosts whose network requests you want to access.
17 </p> 19 </p>
20
18 <pre>{ 21 <pre>{
19 "name": "My extension", 22 "name": "My extension",
20 ... 23 ...
21 <b> "permissions": [ 24 <b> "permissions": [
22 "declarative",
23 "declarativeWebRequest", 25 "declarativeWebRequest",
24 "*://*.google.com" 26 "*://*.google.com"
25 ]</b>, 27 ]</b>,
26 ... 28 ...
27 }</pre> 29 }</pre>
30
28 <h2 id="rules">Rules</h2> 31 <h2 id="rules">Rules</h2>
32
29 <p> 33 <p>
30 The Declarative Web Request API follows the concepts of the <a 34 The Declarative Web Request API follows the concepts of the <a
31 href="events.html#declarative">Declarative API</a>. You can register rules to 35 href="events.html#declarative">Declarative API</a>. You can register rules to
32 the <code>chrome.declarativeWebRequest.onRequest</code> event object. 36 the <code>chrome.declarativeWebRequest.onRequest</code> event object.
33 </p> 37 </p>
38
34 <p> 39 <p>
35 The Declarative Web Request API supports a single type of match criteria, the 40 The Declarative Web Request API supports a single type of match criteria, the
36 <code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network 41 <code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network
37 requests if and only if all listed criteria are met. The following 42 requests if and only if all listed criteria are met. The following
38 <code>RequestMatcher</code> would match a network request when the user enters 43 <code>RequestMatcher</code> would match a network request when the user enters
39 "http://www.example.com" in the URL bar: 44 "http://www.example.com" in the URL bar:
40 </p> 45 </p>
46
41 <pre> 47 <pre>
42 var matcher = new chrome.declarativeWebRequest.RequestMatcher({ 48 var matcher = new chrome.declarativeWebRequest.RequestMatcher({
43 url: { hostSuffix: 'example.com', schemes: ['http'] }, 49 url: { hostSuffix: 'example.com', schemes: ['http'] },
44 resourceType: 'main_frame' 50 resourceType: 'main_frame'
45 }); 51 });
46 </pre> 52 </pre>
53
47 <p> 54 <p>
48 Requests to "https://www.example.com" would be rejected by the 55 Requests to "https://www.example.com" would be rejected by the
49 <code>RequestMatcher</code> due to the scheme. Also all requests for an embedded 56 <code>RequestMatcher</code> due to the scheme. Also all requests for an embedded
50 iframe would be rejected due to the <code>resourceType</code>. 57 iframe would be rejected due to the <code>resourceType</code>.
51 </p> 58 </p>
59
52 <p class="note"> 60 <p class="note">
53 <strong>Note:</strong> All conditions and actions are created via a constructor 61 <strong>Note:</strong> All conditions and actions are created via a constructor
54 as shown in the example above. 62 as shown in the example above.
55 <p> 63 <p>
64
56 <p> 65 <p>
57 In order to cancel all requests to "example.com", you can define a rule as 66 In order to cancel all requests to "example.com", you can define a rule as
58 follows: 67 follows:
59 </p> 68 </p>
60 <pre> 69 <pre>
61 var rule = { 70 var rule = {
62 conditions: [ 71 conditions: [
63 new chrome.declarativeWebRequest.RequestMatcher({ 72 new chrome.declarativeWebRequest.RequestMatcher({
64 url: { hostSuffix: 'example.com' } }) 73 url: { hostSuffix: 'example.com' } })
65 ], 74 ],
66 actions: [ 75 actions: [
67 new chrome.declarativeWebRequest.CancelRequest() 76 new chrome.declarativeWebRequest.CancelRequest()
68 ]}; 77 ]};
69 </pre> 78 </pre>
79
70 <p> 80 <p>
71 In order to cancel all requests to "example.com" and "foobar.com", you can add a 81 In order to cancel all requests to "example.com" and "foobar.com", you can add a
72 second condition, as each condition is sufficient to trigger all specified 82 second condition, as each condition is sufficient to trigger all specified
73 actions: 83 actions:
74 </p> 84 </p>
75 <pre> 85 <pre>
76 var rule2 = { 86 var rule2 = {
77 conditions: [ 87 conditions: [
78 new chrome.declarativeWebRequest.RequestMatcher({ 88 new chrome.declarativeWebRequest.RequestMatcher({
79 url: { hostSuffix: 'example.com' } }), 89 url: { hostSuffix: 'example.com' } }),
80 new chrome.declarativeWebRequest.RequestMatcher({ 90 new chrome.declarativeWebRequest.RequestMatcher({
81 url: { hostSuffix: 'foobar.com' } }) 91 url: { hostSuffix: 'foobar.com' } })
82 ], 92 ],
83 actions: [ 93 actions: [
84 new chrome.declarativeWebRequest.CancelRequest() 94 new chrome.declarativeWebRequest.CancelRequest()
85 ]}; 95 ]};
86 </pre> 96 </pre>
97
87 <p> 98 <p>
88 Register rules as follows: 99 Register rules as follows:
89 </p> 100 </p>
90 <pre> 101 <pre>
91 chrome.declarativeWebRequest.onRequest.addRules([rule2]); 102 chrome.declarativeWebRequest.onRequest.addRules([rule2]);
92 </pre> 103 </pre>
104
93 <p class="note"> 105 <p class="note">
94 <strong>Note:</strong> You should always register or unregister rules in bulk ra ther than 106 <strong>Note:</strong> You should always register or unregister rules in bulk ra ther than
95 individually because each of these operations recreates internal data 107 individually because each of these operations recreates internal data
96 structures. This re-creation is computationally expensive but facilitates a 108 structures. This re-creation is computationally expensive but facilitates a
97 very fast URL matching algorithm for hundreds of thousands of URLs. 109 very fast URL matching algorithm for hundreds of thousands of URLs.
98 </p> 110 </p>
111
99 <h2 id="TODO">Todo</h2> 112 <h2 id="TODO">Todo</h2>
100 <ul> 113 <ul>
101 <li>Explain precedences, once we can ignore rules based on their priority 114 <li>Explain precedences, once we can ignore rules based on their priority
102 (e.g. how can I cancel all requests except for a specific whitelist?) 115 (e.g. how can I cancel all requests except for a specific whitelist?)
103 <li>Explain when conditions can be evaluated, when actions can be executed, 116 <li>Explain when conditions can be evaluated, when actions can be executed,
104 and when rules can be executed (e.g. you cannot cancel a request when you 117 and when rules can be executed (e.g. you cannot cancel a request when you
105 have received the response already) 118 have received the response already)
106 </ul> 119 </ul>
107 <!-- END AUTHORED CONTENT -->
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698