Index: chrome/common/extensions/docs/server2/templates/intros/declarativeWebRequest.html |
diff --git a/chrome/common/extensions/docs/server2/templates/intros/declarativeWebRequest.html b/chrome/common/extensions/docs/server2/templates/intros/declarativeWebRequest.html |
index 2ba2f9b0a07e07e03388154b86ea76b0bfe2ae47..373506eb2946f75768f03df0047ce48d543abbfa 100644 |
--- a/chrome/common/extensions/docs/server2/templates/intros/declarativeWebRequest.html |
+++ b/chrome/common/extensions/docs/server2/templates/intros/declarativeWebRequest.html |
@@ -1,5 +1,5 @@ |
-<!-- BEGIN AUTHORED CONTENT --> |
<h2 id="notes">Notes</h2> |
+ |
<p> |
Use the <code>chrome.declarativeWebRequest</code> module to intercept, block, or |
modify requests in-flight. It is significantly faster than the <a |
@@ -8,29 +8,34 @@ register rules that are evaluated in the browser rather than the |
JavaScript engine which reduces roundtrip latencies and allows for very high |
efficiency. |
</p> |
+ |
<h2 id="manifest">Manifest</h2> |
+ |
<p> |
You must declare the "declarative" and the "declarativeWebRequest" permission in |
the <a href="manifest.html">extension manifest</a> to use this API, |
along with <a href="manifest.html#permissions">host permissions</a> for any |
hosts whose network requests you want to access. |
</p> |
+ |
<pre>{ |
"name": "My extension", |
... |
<b> "permissions": [ |
- "declarative", |
"declarativeWebRequest", |
"*://*.google.com" |
]</b>, |
... |
}</pre> |
+ |
<h2 id="rules">Rules</h2> |
+ |
<p> |
The Declarative Web Request API follows the concepts of the <a |
href="events.html#declarative">Declarative API</a>. You can register rules to |
the <code>chrome.declarativeWebRequest.onRequest</code> event object. |
</p> |
+ |
<p> |
The Declarative Web Request API supports a single type of match criteria, the |
<code>RequestMatcher</code>. The <code>RequestMatcher</code> matches network |
@@ -38,21 +43,25 @@ requests if and only if all listed criteria are met. The following |
<code>RequestMatcher</code> would match a network request when the user enters |
"http://www.example.com" in the URL bar: |
</p> |
+ |
<pre> |
var matcher = new chrome.declarativeWebRequest.RequestMatcher({ |
url: { hostSuffix: 'example.com', schemes: ['http'] }, |
resourceType: 'main_frame' |
}); |
</pre> |
+ |
<p> |
Requests to "https://www.example.com" would be rejected by the |
<code>RequestMatcher</code> due to the scheme. Also all requests for an embedded |
iframe would be rejected due to the <code>resourceType</code>. |
</p> |
+ |
<p class="note"> |
<strong>Note:</strong> All conditions and actions are created via a constructor |
as shown in the example above. |
<p> |
+ |
<p> |
In order to cancel all requests to "example.com", you can define a rule as |
follows: |
@@ -67,6 +76,7 @@ var rule = { |
new chrome.declarativeWebRequest.CancelRequest() |
]}; |
</pre> |
+ |
<p> |
In order to cancel all requests to "example.com" and "foobar.com", you can add a |
second condition, as each condition is sufficient to trigger all specified |
@@ -84,18 +94,21 @@ var rule2 = { |
new chrome.declarativeWebRequest.CancelRequest() |
]}; |
</pre> |
+ |
<p> |
Register rules as follows: |
</p> |
<pre> |
chrome.declarativeWebRequest.onRequest.addRules([rule2]); |
</pre> |
+ |
<p class="note"> |
<strong>Note:</strong> You should always register or unregister rules in bulk rather than |
individually because each of these operations recreates internal data |
structures. This re-creation is computationally expensive but facilitates a |
very fast URL matching algorithm for hundreds of thousands of URLs. |
</p> |
+ |
<h2 id="TODO">Todo</h2> |
<ul> |
<li>Explain precedences, once we can ignore rules based on their priority |
@@ -103,5 +116,4 @@ very fast URL matching algorithm for hundreds of thousands of URLs. |
<li>Explain when conditions can be evaluated, when actions can be executed, |
and when rules can be executed (e.g. you cannot cancel a request when you |
have received the response already) |
-</ul> |
-<!-- END AUTHORED CONTENT --> |
+</ul> |