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

Side by Side Diff: pages/filters.html

Issue 29330725: Noissue - Document the new $generichide and $genericblock filter options (Closed)
Patch Set: Created Nov. 24, 2015, 10:15 a.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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 134 matching lines...) Expand 10 before | Expand all | Expand 10 after
145 <ul> 145 <ul>
146 <li>{{s57 <code><fix>script</fix></code> — external scripts loaded via H TML script tag}}</li> 146 <li>{{s57 <code><fix>script</fix></code> — external scripts loaded via H TML script tag}}</li>
147 <li>{{s58 <code><fix>image</fix></code> — regular images, typically load ed via HTML img tag}}</li> 147 <li>{{s58 <code><fix>image</fix></code> — regular images, typically load ed via HTML img tag}}</li>
148 <li>{{s59 <code><fix>stylesheet</fix></code> — external CSS stylesheet f iles}}</li> 148 <li>{{s59 <code><fix>stylesheet</fix></code> — external CSS stylesheet f iles}}</li>
149 <li>{{s60 <code><fix>object</fix></code> — content handled by browser pl ugins, e.g. Flash or Java}}</li> 149 <li>{{s60 <code><fix>object</fix></code> — content handled by browser pl ugins, e.g. Flash or Java}}</li>
150 <li>{{s62 <code><fix>xmlhttprequest</fix></code> — requests started by t he <a href="{{s62-link http://www.w3.org/TR/XMLHttpRequest/}}">XMLHttpRequest ob ject</a>}}</li> 150 <li>{{s62 <code><fix>xmlhttprequest</fix></code> — requests started by t he <a href="{{s62-link http://www.w3.org/TR/XMLHttpRequest/}}">XMLHttpRequest ob ject</a>}}</li>
151 <li>{{s63 <code><fix>object-subrequest</fix></code> — requests started p lugins like Flash}}</li> 151 <li>{{s63 <code><fix>object-subrequest</fix></code> — requests started p lugins like Flash}}</li>
152 <li>{{s64 <code><fix>subdocument</fix></code> — embedded pages, usually included via HTML frames}}</li> 152 <li>{{s64 <code><fix>subdocument</fix></code> — embedded pages, usually included via HTML frames}}</li>
153 <li>{{s65 <code><fix>document</fix></code> — the page itself (only <a hr ef="#whitelist">exception rules</a> can be applied to the page)}}</li> 153 <li>{{s65 <code><fix>document</fix></code> — the page itself (only <a hr ef="#whitelist">exception rules</a> can be applied to the page)}}</li>
154 <li>{{s66 <code><fix>elemhide</fix></code> — for exception rules only, s imilar to <code><fix>document</fix></code> but only disables <a href="#elemhide" >element hiding rules</a> on the page rather than all filter rules (Adblock Plus 1.2 and higher required)}}</li> 154 <li>{{s66 <code><fix>elemhide</fix></code> — for exception rules only, s imilar to <code><fix>document</fix></code> but only disables <a href="#elemhide" >element hiding rules</a> on the page rather than all filter rules (Adblock Plus 1.2 and higher required)}}</li>
155 <li>{{generichide <code><fix>generichide</fix></code> — for exception ru les only, similar to <code><fix>elemhide</fix></code> but only disables <a href= "#generic-specific">generic</a> element hiding rules on the page (Adblock Plus 2 .6.12 and higher required)}}</li>
156 <li>{{genericblock <code><fix>genericblock</fix></code> — for exception rules only, just like <code><fix>generichide</fix></code> but disables <a href=" #generic-specific">generic</a> blocking rules (Adblock Plus 2.6.12 and higher re quired)}}</li>
155 <li>{{s67 <code><fix>other</fix></code> — types of requests not covered in the list above}}</li> 157 <li>{{s67 <code><fix>other</fix></code> — types of requests not covered in the list above}}</li>
156 </ul> 158 </ul>
157 {{s68 The type options <code><fix>background</fix></code>, <code><fix>xbl< /fix></code>, 159 {{s68 The type options <code><fix>background</fix></code>, <code><fix>xbl< /fix></code>,
158 <code><fix>ping</fix></code> and <code><fix>dtd</fix></code> are outdated and should no 160 <code><fix>ping</fix></code> and <code><fix>dtd</fix></code> are outdated and should no
159 longer be used.}} 161 longer be used.}}
160 </li> 162 </li>
161 <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> 163 <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>
162 <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> 164 <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>
163 <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> 165 <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>
164 <li> 166 <li>
(...skipping 74 matching lines...) Expand 10 before | Expand all | Expand 10 after
239 rules has exactly the same effect as the single rule 241 rules has exactly the same effect as the single rule
240 <code><fix>~example.com##div.textad</fix></code>.}} {{s104 It is recommended t hat you use 242 <code><fix>~example.com##div.textad</fix></code>.}} {{s104 It is recommended t hat you use
241 exception rules only when you cannot change an overly general element hiding r ule, in all the 243 exception rules only when you cannot change an overly general element hiding r ule, in all the
242 other cases limiting this rule to the necessary domains is preferable.}} 244 other cases limiting this rule to the necessary domains is preferable.}}
243 </p> 245 </p>
244 246
245 <h3 id="elemhide_simplified">{{s105 Simplified element hiding syntax}}</h3> 247 <h3 id="elemhide_simplified">{{s105 Simplified element hiding syntax}}</h3>
246 248
247 <p>{{s106 Adblock Plus supports simplified element hiding syntax (e.g. <code>< fix>#div(id=foo)</fix></code>) for backwards compatibility only. Using this synt ax is discouraged, usual CSS selectors are preferred. Support for this syntax mi ght be removed at some point.}}</p> 249 <p>{{s106 Adblock Plus supports simplified element hiding syntax (e.g. <code>< fix>#div(id=foo)</fix></code>) for backwards compatibility only. Using this synt ax is discouraged, usual CSS selectors are preferred. Support for this syntax mi ght be removed at some point.}}</p>
248 250
251 <h3 id="generic-specific">{{generic-specific-title Generic / Specific filters} }</h3>
252
253 <p>{{generic-specific-explanation-p1 With the <code><fix>$generichide</fix></c ode> and <code><fix>$genericblock</fix></code> filter options the distinction be tween generic and specific filters becomes important.}}</p>
254 <p>{{generic-specific-explanation-p2 We classify a filter to be <strong>specif ic</strong> if it matches one or more domains or matches a sitekey. If a filter has no domains specified (or only domain exceptions) and no sitekey then it coun ts as <strong>generic</strong>. For example <code><fix>example.com##div.textad</ fix></code> is a specific filter, where as both <code><fix>##div.textad</fix></c ode> and <code><fix>~example.com##div.textad</fix></code> are generic.}}</p>
255 <p>{{generic-specific-explanation-p3 Note that with blocking rules the domain must be specified under the $domain option for them to be considered specific. F or example <code><fix>||example.com^</fix></code> is considered generic whereas <code><fix>*/ads/*$domain=example.com</fix></code> is site-specific.}}</p>
256
249 <h2 id="sitekey_server">{{s107 Implementing a sitekey on the server}}</h2> 257 <h2 id="sitekey_server">{{s107 Implementing a sitekey on the server}}</h2>
250 258
251 <p> 259 <p>
252 {{s108 For a <a href="#options">sitekey-restricted filter</a> to apply, a webp age needs to return base64-encoded versions of the public key and a signature wh ich Adblock Plus can validate. Currently, this means including them in both the HTTP response header (<code><fix>X-Adblock-Key: abcdpublickeydcba_abcdsignatured cba</fix></code>) and the root tag of the document (<code><fix>&lt;html data-adb lockkey="abcdpublickeydcba_abcdsignaturedcba"&gt;</fix></code>).}} 260 {{s108 For a <a href="#options">sitekey-restricted filter</a> to apply, a webp age needs to return base64-encoded versions of the public key and a signature wh ich Adblock Plus can validate. Currently, this means including them in both the HTTP response header (<code><fix>X-Adblock-Key: abcdpublickeydcba_abcdsignatured cba</fix></code>) and the root tag of the document (<code><fix>&lt;html data-adb lockkey="abcdpublickeydcba_abcdsignaturedcba"&gt;</fix></code>).}}
253 </p> 261 </p>
254 262
255 <p> 263 <p>
256 {{s109 First you need to create a private RSA key (preferably 512 bit to keep the transfer volume low) and then a DER representation of the public key.}} 264 {{s109 First you need to create a private RSA key (preferably 512 bit to keep the transfer volume low) and then a DER representation of the public key.}}
257 </p> 265 </p>
258 266
259 <p> 267 <p>
260 {{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:}} 268 {{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:}}
261 </p> 269 </p>
262 270
263 <pre> 271 <pre>
264 /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv :30.0) Gecko/20100101 Firefox/30.0 272 /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv :30.0) Gecko/20100101 Firefox/30.0
265 </pre> 273 </pre>
266 274
267 <p> 275 <p>
268 {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}} 276 {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}
269 </p> 277 </p>
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld