Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Delta Between Two Patch Sets: pages/filters.html

Issue 29767583: Issue 6626 - Document the rewrite filter option (Closed) Base URL: https://hg.adblockplus.org/web.adblockplus.org/
Left Patch Set: Update from gdoc Created May 8, 2018, 1:36 p.m.
Right Patch Set: Addressed Julian's comments. Added a note about the restriction on content for rewriting. Created May 29, 2018, 7:04 p.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « pages/filter-cheatsheet.html ('k') | no next file » | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 title=Writing Adblock Plus filters 1 title=Writing Adblock Plus filters
2 2
3 3
4 <p>{{s1 Current Adblock Plus versions allow you to "tweak" your filters in many different ways. This document explains the choices that you have and how they ca n be used.}}</p> 4 <p>{{s1 Current Adblock Plus versions allow you to "tweak" your filters in many different ways. This document explains the choices that you have and how they ca n be used.}}</p>
5 5
6 <p>{{s2 <em>Disclaimer</em>: All filter examples given here are really only ex amples and are not meant to be used.}}</p> 6 <p>{{s2 <em>Disclaimer</em>: All filter examples given here are really only ex amples and are not meant to be used.}}</p>
7 7
8 <h2 id="introduction">{{s3 Introduction to Adblock Plus filters}}</h2> 8 <h2 id="introduction">{{s3 Introduction to Adblock Plus filters}}</h2>
9 9
10 <p>{{s4 The options described in this section should be enough for users who h ave to create a filter occasionally.}}</p> 10 <p>{{s4 The options described in this section should be enough for users who h ave to create a filter occasionally.}}</p>
(...skipping 152 matching lines...) Expand 10 before | Expand all | Expand 10 after
163 {{deprecated-options The type options <code><fix>background</fix></code>, 163 {{deprecated-options The type options <code><fix>background</fix></code>,
164 <code><fix>xbl</fix></code> and <code><fix>dtd</fix></code> are outdated 164 <code><fix>xbl</fix></code> and <code><fix>dtd</fix></code> are outdated
165 and should no longer be used.}} 165 and should no longer be used.}}
166 </li> 166 </li>
167 <li>{{s69 Inverse type options: specify the element types the filter should <strong>not</strong> be applied to. Possible inverse type options: <code><fix>~s cript</fix></code>, <code><fix>~image</fix></code>, <code><fix>~stylesheet</fix> </code>, <code><fix>~object</fix></code>, <code><fix>~xmlhttprequest</fix></code >, <code><fix>~object-subrequest</fix></code>, <code><fix>~subdocument</fix></co de>, <code><fix>~document</fix></code>, <code><fix>~elemhide</fix></code>, <code ><fix>~other</fix></code>}}</li> 167 <li>{{s69 Inverse type options: specify the element types the filter should <strong>not</strong> be applied to. Possible inverse type options: <code><fix>~s cript</fix></code>, <code><fix>~image</fix></code>, <code><fix>~stylesheet</fix> </code>, <code><fix>~object</fix></code>, <code><fix>~xmlhttprequest</fix></code >, <code><fix>~object-subrequest</fix></code>, <code><fix>~subdocument</fix></co de>, <code><fix>~document</fix></code>, <code><fix>~elemhide</fix></code>, <code ><fix>~other</fix></code>}}</li>
168 <li>{{s70 Restriction to third-party/first-party requests: If the <code><fix >third-party</fix></code> option is specified, the filter is only applied to req uests from a different origin than the currently viewed page. Similarly, <code>< fix>~third-party</fix></code> restricts the filter to requests from the same ori gin as the currently viewed page.}}</li> 168 <li>{{s70 Restriction to third-party/first-party requests: If the <code><fix >third-party</fix></code> option is specified, the filter is only applied to req uests from a different origin than the currently viewed page. Similarly, <code>< fix>~third-party</fix></code> restricts the filter to requests from the same ori gin as the currently viewed page.}}</li>
169 <li>{{s71 Domain restrictions: The option <code><fix>domain=example.com</fix ></code> means that the filter should only be applied on pages from "example.com " domain. Multiple domains can be specified using "|" as separator: with the opt ion <code><fix>domain=example.com|example.net</fix></code> the filter will only be applied on pages from "example.com" or "example.net" domains. If a domain nam e is preceded with "~", the filter should <strong>not</strong> be applied on pag es from this domain. For example, <code><fix>domain=~example.com</fix></code> me ans that the filter should be applied on pages from any domain but "example.com" and <code><fix>domain=example.com|~foo.example.com</fix></code> restricts the f ilter to the "example.com" domain with the exception of "foo.example.com" subdom ain.}}</li> 169 <li>{{s71 Domain restrictions: The option <code><fix>domain=example.com</fix ></code> means that the filter should only be applied on pages from "example.com " domain. Multiple domains can be specified using "|" as separator: with the opt ion <code><fix>domain=example.com|example.net</fix></code> the filter will only be applied on pages from "example.com" or "example.net" domains. If a domain nam e is preceded with "~", the filter should <strong>not</strong> be applied on pag es from this domain. For example, <code><fix>domain=~example.com</fix></code> me ans that the filter should be applied on pages from any domain but "example.com" and <code><fix>domain=example.com|~foo.example.com</fix></code> restricts the f ilter to the "example.com" domain with the exception of "foo.example.com" subdom ain.}}</li>
170 <li> 170 <li>
171 {{s72 Sitekey restrictions: The option <code><fix>sitekey=abcdsitekeydcba< /fix></code> means that the filter should only be applied on pages that provide a public key and a signature which can be verified by that very same public key that is also contained in the filter (but without the trailing =). Multiple site keys can be specified using "|" as separator: with the option <code><fix>sitekey =abcdsitekeydcba|bcdesitekeyedcb</fix></code> the filter will only be applied on pages providing either sitekey "abcdsitekeydcba" or "bcdesitekeyedcb". This is similar to domain restrictions but allows covering scenarios where a single filt er should apply to a very large number of domains. Note that sitekey restriction s require <a href="#sitekey_server">modifications on the server-side</a>.}} 171 {{s72 Sitekey restrictions: The option <code><fix>sitekey=abcdsitekeydcba< /fix></code> means that the filter should only be applied on pages that provide a public key and a signature which can be verified by that very same public key that is also contained in the filter (but without the trailing =). Multiple site keys can be specified using "|" as separator: with the option <code><fix>sitekey =abcdsitekeydcba|bcdesitekeyedcb</fix></code> the filter will only be applied on pages providing either sitekey "abcdsitekeydcba" or "bcdesitekeyedcb". This is similar to domain restrictions but allows covering scenarios where a single filt er should apply to a very large number of domains. Note that sitekey restriction s require <a href="#sitekey_server">modifications on the server-side</a>.}}
172 </li> 172 </li>
173 <li>
174 {{csp Content Security Policies: The option <code><fix>csp=script-src: 'no ne'</fix></code> causes a Content Security Policy header of <code><fix>script-sr c: 'none'</fix></code> to be injected into HTTP responses for requested document s matching the filter — assuming that exception rules with the same option don't also match and that the document isn’t whitelisted. The Content Security Policy <code><fix>script-src: 'none'</fix></code> would in turn block all scripts — in cluding inline — for the document. This filter option should generally be avoide d, except as a last resort to counter advanced circumvention. (Adblock Plus 3.1 or higher required.)}}
175 </li>
173 <li>{{s73 <code><fix>match-case</fix></code> — makes the filter only apply t o addresses with matching letter case, e.g. the filter <code><fix>*/BannerAd.gif $match-case</fix></code> will block <code><fix>http://example.com/BannerAd.gif</ fix></code> but not <code><fix>http://example.com/bannerad.gif</fix></code>.}}</ li> 176 <li>{{s73 <code><fix>match-case</fix></code> — makes the filter only apply t o addresses with matching letter case, e.g. the filter <code><fix>*/BannerAd.gif $match-case</fix></code> will block <code><fix>http://example.com/BannerAd.gif</ fix></code> but not <code><fix>http://example.com/bannerad.gif</fix></code>.}}</ li>
174 <li>{{s74 <code><fix>collapse</fix></code> — this option will override the g lobal "Hide placeholders of blocked elements" option and make sure the filter al ways hides the element. Similarly the <code><fix>~collapse</fix></code> option w ill make sure the filter never hides the element.}}</li> 177 <li>{{s74 <code><fix>collapse</fix></code> — this option will override the g lobal "Hide placeholders of blocked elements" option and make sure the filter al ways hides the element. Similarly the <code><fix>~collapse</fix></code> option w ill make sure the filter never hides the element.}}</li>
175 <li> 178 <li>
176 {{s75 <code><fix>donottrack</fix></code> — for any address matching a bloc king rule with 179 {{s75 <code><fix>donottrack</fix></code> — for any address matching a bloc king rule with
177 this option and not matching any exception rules with this option a 180 this option and not matching any exception rules with this option a
178 <a href="http://donottrack.us/">Do-Not-Track header</a> will be sent (requ ires 181 <a href="http://donottrack.us/">Do-Not-Track header</a> will be sent (requ ires
179 Adblock Plus 1.3.5 or higher).}} {{s76 For backwards compatibility it is r ecommended 182 Adblock Plus 1.3.5 or higher).}} {{s76 For backwards compatibility it is r ecommended
180 to use this option in combination with contradicting type options, this wi ll prevent this 183 to use this option in combination with contradicting type options, this wi ll prevent this
181 filter from blocking anything in earlier Adblock Plus versions: 184 filter from blocking anything in earlier Adblock Plus versions:
182 <code><fix>*$donottrack,image,~image</fix></code>}} 185 <code><fix>*$donottrack,image,~image</fix></code>}}
183 </li> 186 </li>
184 <li> 187 <li>
185 {{rewriteoption Rewrite the URL with the option <code><fix>rewrite=</fix>< /code>. You may want to create a regular expression filter to perform the rewrit e operation. In that case, you can use <code><fix>$n</fix></code> in the rewrite argument, with n being a number between 1 and 100, to insert the n-th parenthes is submatch of the filter regular expression. Anything not explicitly matched by it will be added in the rewritten string. For example <code><fix>/(server.com\/ assets\/file.php)\?.*$/$rewrite=$1</fix></code> will strip everything that comes after ".php" and redirects the request to the resulting URL. If there is no que ry parameter (i.e. no '?'), this filter won't match. The rewrite parameter has t he same syntax as JavaScript’s <code><fix>String.prototype.replace()</fix></code > when using a regular expression instead of a substring. If both, a filter with /without <code><fix>$rewrite</fix></code> option matches, the behavior is undefi ned, i.e. the request might either be blocked or redirected. (Adblock Plus 3.2 o r higher required.)}} 188 {{rewriteoption Rewrite the URL with the option <code><fix>rewrite=</fix>< /code>. You may want to create a regular expression filter to perform the rewrit e operation. In that case, you can use <code><fix>$n</fix></code> in the rewrite argument, with <code><fix>n</fix></code> being a number between 1 and 100, to i nsert the n-th parenthesis submatch of the filter regular expression. Anything n ot explicitly matched by it will be added in the rewritten string. For example < code><fix>/(server\.com\/assets\/file.php)\?.*$/$rewrite=$1</fix></code> will st rip everything that comes after ".php" and redirects the request to the resultin g URL. If there is no query string (i.e. no '?'), this filter won't match. The r ewrite parameter has the same syntax as JavaScript’s <a href="https://developer. mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Sp ecifying_a_string_as_a_parameter"><code><fix>String.prototype.replace()</fix></c ode></a>. The resulting URL must have the same origin; in case it is rewritten t o a relative URL, the origin gets added back. Also, rewrite for scripts, subdocu ments, objects, requests from within objects (like Flash) are not possible for s ecurity reason; even if explicitly stated by the filter. If both, a filter with/ without <code><fix>$rewrite</fix></code> option matches, the behavior is undefin ed, i.e. the request might either be blocked or redirected. (Adblock Plus 3.2 or higher required.)}}
Manish Jethani 2018/05/10 02:47:39 We should probably also mention about the requirem
186 </li> 189 </li>
187 </ul> 190 </ul>
188 191
189 <h4 id="regexps">{{s77 Using regular expressions}}</h4> 192 <h4 id="regexps">{{s77 Using regular expressions}}</h4>
190 193
191 <p>{{s79 If you want even more control about what your filters match and what they don't match, you can use regular expressions. For example the filter <code> <fix>/banner\d+/</fix></code> will match <code><fix>banner123</fix></code> and < code><fix>banner321</fix></code> but not <code><fix>banners</fix></code>. You ca n check out <a href="{{s79-link https://developer.mozilla.org/en/Core_JavaScript _1.5_Guide/Regular_Expressions#Writing_a_Regular_Expression_Pattern}}">documenta tion on regular expressions</a> to learn how to write them.}}</p> 194 <p>{{s79 If you want even more control about what your filters match and what they don't match, you can use regular expressions. For example the filter <code> <fix>/banner\d+/</fix></code> will match <code><fix>banner123</fix></code> and < code><fix>banner321</fix></code> but not <code><fix>banners</fix></code>. You ca n check out <a href="{{s79-link https://developer.mozilla.org/en/Core_JavaScript _1.5_Guide/Regular_Expressions#Writing_a_Regular_Expression_Pattern}}">documenta tion on regular expressions</a> to learn how to write them.}}</p>
192 195
193 <p>{{s80 <em>Note</em>: For performance reasons it is recommended not to use r egular expressions if they can be avoided.}}</p> 196 <p>{{s80 <em>Note</em>: For performance reasons it is recommended not to use r egular expressions if they can be avoided.}}</p>
194 197
195 <h2 id="elemhide">{{s81 Element hiding}}</h2> 198 <h2 id="elemhide">{{s81 Element hiding}}</h2>
(...skipping 106 matching lines...) Expand 10 before | Expand all | Expand 10 after
302 {{s110 The data used for creating the signature is a concatenated list of requ est variables (namely URI, host and user agent) separated by the <code><fix>NUL< /fix></code> character "\0". For example:}} 305 {{s110 The data used for creating the signature is a concatenated list of requ est variables (namely URI, host and user agent) separated by the <code><fix>NUL< /fix></code> character "\0". For example:}}
303 </p> 306 </p>
304 307
305 <pre> 308 <pre>
306 /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv :30.0) Gecko/20100101 Firefox/30.0 309 /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv :30.0) Gecko/20100101 Firefox/30.0
307 </pre> 310 </pre>
308 311
309 <p> 312 <p>
310 {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}} 313 {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}
311 </p> 314 </p>
LEFTRIGHT

Powered by Google App Engine
This is Rietveld