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

Delta Between Two Patch Sets: pages/filters.html

Issue 29482703: Issue 5353 - Add advanced element hiding filters documentation (Closed) Base URL: https://hg.adblockplus.org/web.adblockplus.org/
Left Patch Set: Changed the string ids to be readable Created July 10, 2017, 4:19 p.m.
Right Patch Set: Added [header] Created July 28, 2017, 8:03 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>
11 11
12 <h3 id="basic">{{s5 Basic filter rules}}</h3> 12 <h3 id="basic">{{s5 Basic filter rules}}</h3>
13 13
14 <p>{{s6 The most trivial filter you can define is of course the address of ban ner you want to block. However, often this address changes every time you open a page. For example it could be <code><fix>http://example.com/ads/banner123.gif</ fix></code> where 123 is a random number. Here blocking the complete address won 't help you, you need a more general filter — like <code><fix>http://example.com /ads/banner*.gif</fix></code>. Or maybe even <code><fix>http://example.com/ads/* </fix></code>.}}</p> 14 <p>{{s6 The most trivial filter you can define is of course the address of ban ner you want to block. However, often this address changes every time you open a page. For example it could be <code><fix>http://example.com/ads/banner123.gif</ fix></code> where 123 is a random number. Here blocking the complete address won 't help you, you need a more general filter — like <code><fix>http://example.com /ads/banner*.gif</fix></code>. Or maybe even <code><fix>http://example.com/ads/* </fix></code>.}}</p>
15 15
16 <p>{{s7 <em>Note</em>: Make sure that you are not replacing too much by wildca rds. The filter <code><fix>http://example.com/*</fix></code> will definitely blo ck all banners but it will also block everything else from example.com that you still might want to see.}}</p> 16 <p>{{s7 <em>Note</em>: Make sure that you are not replacing too much by wildca rds. The filter <code><fix>http://example.com/*</fix></code> will definitely blo ck all banners but it will also block everything else from example.com that you still might want to see.}}</p>
17 17
18 <h3 id="whitelist">{{s8 Defining exception rules}}</h3> 18 <h3 id="whitelist">{{s8 Defining exception rules}}</h3>
19 19
20 <p>{{s9 Sometimes you will notice that one of your filters that is usually wor king quite well blocks in some case blocks something that it shouldn't be blocki ng. You don't want to remove this filter but you still don't want it to match in this one case.}}</p> 20 <p>{{s9 Once in a while you may notice that one of your filters, that normally works well, is blocking something that it shouldn't block. You don't want to re move this filter but you still don't want it to match in this one case.}}</p>
21 21
22 <p>{{s10 That's what exception rules are good for — they allow you to define c ases where filters shouldn't be applied. For example if you are unhappy with you r filter <code><fix>adv</fix></code> blocking <code><fix>http://example.com/advi ce.html</fix></code>, you can define an exception rule <code><fix>@@advice</fix> </code>. Exception rules are no different from filter rules, you can use wildcar ds or regular expressions. You only have to precede them by <code><fix>@@</fix>< /code> to indicate an exception rule.}}</p> 22 <p>{{s10 That's what exception rules are good for — they allow you to define c ases where filters shouldn't be applied. For example if you are unhappy with you r filter <code><fix>adv</fix></code> blocking <code><fix>http://example.com/advi ce.html</fix></code>, you can define an exception rule <code><fix>@@advice</fix> </code>. Exception rules are no different from filter rules, you can use wildcar ds or regular expressions. You only have to precede them by <code><fix>@@</fix>< /code> to indicate an exception rule.}}</p>
23 23
24 <p>{{s11 Exception rules can do more. If you specify <code><fix>$document</fix ></code> option you will get an exception for the entire page. For example, if y our exception rule is <code><fix>@@||example.com^$document</fix></code> and you open some page from example.com — Adblock Plus will be entirely disabled on this page and nothing will be blocked.}}</p> 24 <p>{{s11 Exception rules can do more. If you specify <code><fix>$document</fix ></code> option you will get an exception for the entire page. For example, if y our exception rule is <code><fix>@@||example.com^$document</fix></code> and you open some page from example.com — Adblock Plus will be entirely disabled on this page and nothing will be blocked.}}</p>
25 25
26 <h3 id="anchors">{{s12 Matching at beginning/end of an address}}</h3> 26 <h3 id="anchors">{{s12 Matching at beginning/end of an address}}</h3>
27 27
28 <p>{{s13 Usually Adblock Plus treats every filter as if it had a wildcard at i ts beginning and end, e.g. there is not difference between the filters <code><fi x>ad</fix></code> and <code><fix>*ad*</fix></code>. While this is usually unprob lematic, sometimes you wish that the filter you defined only matches at the begi nning or end of an address. For example you might want to block all Flash, but i f you add the filter <code><fix>swf</fix></code> the address <code><fix>http://e xample.com/swf/index.html</fix></code> will also be blocked.}}</p> 28 <p>{{s13 Usually Adblock Plus treats every filter as if it had a wildcard at i ts beginning and end, e.g. there is not difference between the filters <code><fi x>ad</fix></code> and <code><fix>*ad*</fix></code>. While this is usually unprob lematic, sometimes you wish that the filter you defined only matches at the begi nning or end of an address. For example you might want to block all Flash, but i f you add the filter <code><fix>swf</fix></code> the address <code><fix>http://e xample.com/swf/index.html</fix></code> will also be blocked.}}</p>
29 29
30 <p>{{s14 Solution to this problem: add a pipe symbol to the filter to show tha t there should be definitely the end of the address at this point. For example t he filter <code><fix>swf|</fix></code> will block <code><fix>http://example.com/ annoyingflash.swf</fix></code> but not <code><fix>http://example.com/swf/index.h tml</fix></code>. And the filter <code>|http://baddomain.example/</code> will bl ock <code>http://baddomain.example/banner.gif</code> but not <code>http://gooddo main.example/analyze?http://baddomain.example</code>.}}</p> 30 <p>{{s14 Solution to this problem: add a pipe symbol to the filter to show tha t there should be definitely the end of the address at this point. For example t he filter <code><fix>swf|</fix></code> will block <code><fix>http://example.com/ annoyingflash.swf</fix></code> but not <code><fix>http://example.com/swf/index.h tml</fix></code>. And the filter <code>|http://baddomain.example/</code> will bl ock <code>http://baddomain.example/banner.gif</code> but not <code>http://gooddo main.example/analyze?http://baddomain.example</code>.}}</p>
(...skipping 195 matching lines...) Expand 10 before | Expand all | Expand 10 after
226 <h3 id="elemhide_attributes">{{s93 Attribute selectors}}</h3> 226 <h3 id="elemhide_attributes">{{s93 Attribute selectors}}</h3>
227 227
228 <p>{{s94 Some advertisers don't make it easy for you — their text advertisemen ts have neither an id nor a class attribute. You can use other attributes to hid e those, for example <code><fix>##table[width="80%"]</fix></code> will hide tabl es with width attribute set to 80%. If you don't want to specify the full value of the attribute, <code><fix>##div[title*="adv"]</fix></code> will hide all div elements with title attribute containing the string "adv". You can also check th e beginning and the end of an attribute, for example <code><fix>##div[title^="ad v"][title$="ert"]</fix></code> will hide div elements with title starting with " adv" and ending with "ert". As you see, you can also use multiple conditions — < code><fix>table[width="80%"][bgcolor="white"]</fix></code> will match tables wit h width attribute set to 80% and bgcolor attribute set to white.}}</p> 228 <p>{{s94 Some advertisers don't make it easy for you — their text advertisemen ts have neither an id nor a class attribute. You can use other attributes to hid e those, for example <code><fix>##table[width="80%"]</fix></code> will hide tabl es with width attribute set to 80%. If you don't want to specify the full value of the attribute, <code><fix>##div[title*="adv"]</fix></code> will hide all div elements with title attribute containing the string "adv". You can also check th e beginning and the end of an attribute, for example <code><fix>##div[title^="ad v"][title$="ert"]</fix></code> will hide div elements with title starting with " adv" and ending with "ert". As you see, you can also use multiple conditions — < code><fix>table[width="80%"][bgcolor="white"]</fix></code> will match tables wit h width attribute set to 80% and bgcolor attribute set to white.}}</p>
229 229
230 <h3 id="elemhide_css">{{s95 Advanced selectors}}</h3> 230 <h3 id="elemhide_css">{{s95 Advanced selectors}}</h3>
231 231
232 <p>{{s97 In general, any CSS selector supported by Firefox can be used for ele ment hiding. For example the following rule will hide anything following a div e lement with class "adheader": <code><fix>##div.adheader + *</fix></code>. For a full list of CSS list see <a href="{{s97-link http://www.w3.org/TR/css3-selector s/}}">W3C CSS specification</a> (note that not all selectors are supported by Fi refox yet).}}</p> 232 <p>{{s97 In general, any CSS selector supported by Firefox can be used for ele ment hiding. For example the following rule will hide anything following a div e lement with class "adheader": <code><fix>##div.adheader + *</fix></code>. For a full list of CSS list see <a href="{{s97-link http://www.w3.org/TR/css3-selector s/}}">W3C CSS specification</a> (note that not all selectors are supported by Fi refox yet).}}</p>
233 233
234 <p>{{s98 <em>Note</em>: This functionality is for advanced users only, you sho uld be comfortable with CSS selectors to use it. Adblock Plus won't be able to c heck the syntax of the selector you are adding, if you use invalid CSS syntax yo u might break other (valid) rules you have. Check JavaScript Console for CSS err ors.}}</p> 234 <p>{{s98 <em>Note</em>: This functionality is for advanced users only, you sho uld be comfortable with CSS selectors to use it. Adblock Plus won't be able to c heck the syntax of the selector you are adding, if you use invalid CSS syntax yo u might break other (valid) rules you have. Check JavaScript Console for CSS err ors.}}</p>
235 235
236 <h3 id="elemhide-emulation">{{ elemhide-emulation-heading[heading] Extended CSS selectors (Adblock Plus specific) }}</h3>
237
238 <p>
239 {{ elemhide-emulation-1 Sometimes the standard CSS selectors aren't powerful e nough to hide an advertisement, for those cases we have added some new ones, nam ely <code><fix>:-abp-has()</fix></code> and <code><fix>:-abp-properties()</fix>< /code> (requires Adblock Plus 1.13.3 for Chrome and Opera or higher). }}
240 </p>
241 <p>
242 {{ elemhide-emulation-2 When writing an element hiding filter that makes use o f these extended selectors you must use the <code><fix>#?#</fix></code> syntax, e.g. <code><fix>example.com#?#selector</fix></code>. But it's important to note that doing so carries a performance impact, so do so sparingly and make sure tho se filters are specific to as few domains and elements as possible. }}
243 </p>
244 <h4>:-abp-properties()</h4>
245 <p>
246 {{ abp-properties-1 <code><fix>:-abp-properties(properties)</fix></code> will select elements based upon stylesheet properties. For example <code><fix>:-abp-p roperties(width:300px;height:250px;)</fix></code> will select elements that have a corresponding CSS rule in a stylesheet which sets the <code><fix>width</fix>< /code> and <code><fix>height</fix></code> to the values <code><fix>300px</fix></ code> and <code><fix>250px</fix></code> respectively. Property names are matched case-insensitively. Furthermore, wildcards can be used so that <code><fix>:-abp -properties(width:*px;height:250px;)</fix></code> will match any width specified in pixels and a height of 250 pixels. }}
247 </p>
248 <p>
249 {{ abp-properties-2 You can also use <a href="https://developer.mozilla.org/en -US/docs/Web/JavaScript/Guide/Regular_Expressions">regular expressions</a> by su rrounding the properties expression with "/". For example, <code><fix>:-abp-prop erties(/width:30[2-8]px;height:250px;/)</fix></code> will match widths between 3 02 and 308 pixels and a height of 250 pixels. }}
250 </p>
251 <p>
252 {{ abp-properties-3 <em>Note</em>: The <a href="https://adblockplus.org/develo pment-builds/new-css-property-filter-syntax">older syntax</a> for the CSS proper ty filters is deprecated and will be automatically converted to the new format&n bsp;. The syntax to select the style properties remain the same. For example, <c ode><fix>[-abp-properties='width:300px;height:250px;']</fix></code> will be conv erted to <code><fix>:-abp-properties(width:300px;height:250px;)</fix></code>. }}
253 </p>
254 <h4>:-abp-has()</h4>
255 <p>
256 {{ abp-has-1 <code><fix>:-abp-has(selector)</fix></code> will select elements based on their content. For example <code><fix>:-abp-has(> div > a.advertiser)</ fix></code> will select elements that contain as a direct descendant a <code><fi x>&lt;div&gt;</fix></code> that contains an <code><fix>&lt;a&gt;</fix></code> wi th the class <code><fix>advertiser</fix></code>. The inner selector can be relat ive to the element scope, and can use any of the pseudo-selectors, including <co de><fix>:-abp-has()</fix></code> and will determine whether the selection will o ccur. }}
257 </p>
258
236 <h3 id="elemhide_exceptions">{{s99 Exception rules}}</h3> 259 <h3 id="elemhide_exceptions">{{s99 Exception rules}}</h3>
237 260
238 <p> 261 <p>
239 {{s100 Exception rules can disable existing rules on particular domains.}} {{s 101 These are mostly 262 {{s100 Exception rules can disable existing rules on particular domains.}} {{s 101 These are mostly
240 useful to filter subscription authors who are extending another filter subscri ption that they 263 useful to filter subscription authors who are extending another filter subscri ption that they
241 cannot change.}} {{s102 For example, the rule <code><fix>##div.textad</fix></c ode> can be 264 cannot change.}} {{s102 For example, the rule <code><fix>##div.textad</fix></c ode> can be
242 disabled on <code><fix>example.com</fix></code> using the exception rule 265 disabled on <code><fix>example.com</fix></code> using the exception rule
243 <code><fix>example.com#@#div.textad</fix></code>.}} {{s103 The combination of these two 266 <code><fix>example.com#@#div.textad</fix></code>.}} {{s103 The combination of these two
244 rules has exactly the same effect as the single rule 267 rules has exactly the same effect as the single rule
245 <code><fix>~example.com##div.textad</fix></code>.}} {{s104 It is recommended t hat you use 268 <code><fix>~example.com##div.textad</fix></code>.}} {{s104 It is recommended t hat you use
246 exception rules only when you cannot change an overly general element hiding r ule, in all the 269 exception rules only when you cannot change an overly general element hiding r ule, in all the
247 other cases limiting this rule to the necessary domains is preferable.}} 270 other cases limiting this rule to the necessary domains is preferable.}}
248 </p> 271 {{ exception-rules These exceptions will be applied to <a href="#elemhide-emul ation">advanced pseudo-selector rules</a> as well. }}
249
250 <h3 id="elemhide-emulation">{{elemhide-emulation-title Advanced element hiding}} </h3>
kzar 2017/07/11 12:56:17 It seems more logical to me to put this new sectio
hub 2017/07/11 22:25:58 make sense
251
252 <p>
253 {{elemhide-emulation-explanation-p1 Advanced hiding rules will hide elements t hat matches the CSS selector directly. <code><fix>example.com#?#div.textad</fix> </code> will directly hide <code><fix>&lt;div&gt;</fix></code> elements with the <code><fix>textad</fix></code> class. These filters only exist as <a href="#gen eric-specific">specific filters</a>: a domain is mandatory.}}
kzar 2017/07/11 12:56:17 I don't understand what you mean by "matches the C
254 </p>
255 <p>
256 {{elemhide-emulation-explanation-p2 <a href="#elemhide_exceptions">Exception r ules</a> above can be applied to the advanced hiding rules the same way.}}
kzar 2017/07/11 12:56:17 This sentence doesn't seem to add much.
hub 2017/07/11 22:25:58 I'll remove this.
257 </p>
258 <p>
259 {{elemhide-emulation-explanation-p3 Advanced hiding rules also introduce new p seudo-class selectors for when a plain CSS selector isn't enough. <code><fix>:-a bp-has(selector)</fix></code> will select the element whose content match the en closed selector. <code><fix>:-abp-properties(properties)</fix></code> will match elements based on their CSS style properties.}}
260 </p>
261 <p>
262 {{elemhide-emulation-explanation-p4 <code><fix>:-abp-properties(properties)</f ix></code> will select elements based on properties of their stylesheet. For exa mple, <code><fix>:-abp-properties(width:300px;height:250px;)</fix></code> will s elect elements that have <code><fix>width</fix></code> and <code><fix>height</fi x></code> set to the specified values <code><fix>300px</fix></code> and <code><f ix>250px</fix></code> respectively. The <a href="https://adblockplus.org/develop ment-builds/new-css-property-filter-syntax">older syntax</a> for the filters is deprecated and will be automatically converted to the new format&nbsp;; the synt ax to select the style properties remain the same.}}
kzar 2017/07/11 12:56:17 Nit: It looks wrong to me to put a comma after "Fo
hub 2017/07/11 22:25:58 Acknowledged.
263 </p>
264 <p>
265 {{elemhide-emulation-explanation-p5 <code><fix>:-abp-has(selector)</fix></code > will select elements based on their content. For example, <code><fix>:-abp-has (> div > a.advertiser)</fix></code> will select elements that contain as a direc t descendant a <code><fix>&lt;div&gt;</fix></code> that contains an <code><fix>& lt;a&gt;</fix></code> with the class <code><fix>advertiser</fix></code>. The inn er selector matching determine whether the selection occur. It is important that <code><fix>:-abp-has()</fix></code> be applied to a restricted number of elemen ts to avoid performance issues. Like any regular pseudo-class you can combine it with the CSS selector syntax.}}
kzar 2017/07/11 12:56:17 Perhaps the sentence about limiting the number of
hub 2017/07/11 22:25:58 Acknowledged.
266 </p> 272 </p>
267 273
268 <h3 id="elemhide_simplified">{{s105 Simplified element hiding syntax}}</h3> 274 <h3 id="elemhide_simplified">{{s105 Simplified element hiding syntax}}</h3>
269 275
270 <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> 276 <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>
271 277
272 <h3 id="generic-specific">{{generic-specific-title Generic / Specific filters} }</h3> 278 <h3 id="generic-specific">{{generic-specific-title Generic / Specific filters} }</h3>
273 279
274 <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> 280 <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>
275 <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, whereas both <code><fix>##div.textad</fix></c ode> and <code><fix>~example.com##div.textad</fix></code> are generic.}}</p> 281 <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, whereas both <code><fix>##div.textad</fix></c ode> and <code><fix>~example.com##div.textad</fix></code> are generic.}}</p>
(...skipping 13 matching lines...) Expand all
289 {{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:}} 295 {{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:}}
290 </p> 296 </p>
291 297
292 <pre> 298 <pre>
293 /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv :30.0) Gecko/20100101 Firefox/30.0 299 /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv :30.0) Gecko/20100101 Firefox/30.0
294 </pre> 300 </pre>
295 301
296 <p> 302 <p>
297 {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}} 303 {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}
298 </p> 304 </p>
LEFTRIGHT

Powered by Google App Engine
This is Rietveld