Issue 5353 - Add advanced element hiding filters documentation

pages/filters.html

 title=Writing Adblock Plus filters
 
 
 <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 can be used.}}</p>
 
   <p>{{s2 <em>Disclaimer</em>: All filter examples given here are really only examples and are not meant to be used.}}</p>
 
   <h2 id="introduction">{{s3 Introduction to Adblock Plus filters}}</h2>
 
   <p>{{s4 The options described in this section should be enough for users who have to create a filter occasionally.}}</p>
 
   <h3 id="basic">{{s5 Basic filter rules}}</h3>
 
   <p>{{s6 The most trivial filter you can define is of course the address of banner 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>
 
   <p>{{s7 <em>Note</em>: Make sure that you are not replacing too much by wildcards. The filter <code><fix>http://example.com/*</fix></code> will definitely block all banners but it will also block everything else from example.com that you still might want to see.}}</p>
 
   <h3 id="whitelist">{{s8 Defining exception rules}}</h3>
 
-  <p>{{s9 Sometimes you will notice that one of your filters that is usually working quite well blocks in some case blocks something that it shouldn't be blocking. You don't want to remove this filter but you still don't want it to match in this one case.}}</p>
+  <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 remove this filter but you still don't want it to match in this one case.}}</p>
 
   <p>{{s10 That's what exception rules are good for — they allow you to define cases where filters shouldn't be applied. For example if you are unhappy with your filter <code><fix>adv</fix></code> blocking <code><fix>http://example.com/advice.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 wildcards or regular expressions. You only have to precede them by <code><fix>@@</fix></code> to indicate an exception rule.}}</p>
 
   <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 your 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>
 
   <h3 id="anchors">{{s12 Matching at beginning/end of an address}}</h3>
 
   <p>{{s13 Usually Adblock Plus treats every filter as if it had a wildcard at its beginning and end, e.g. there is not difference between the filters <code><fix>ad</fix></code> and <code><fix>*ad*</fix></code>. While this is usually unproblematic, sometimes you wish that the filter you defined only matches at the beginning or end of an address. For example you might want to block all Flash, but if you add the filter <code><fix>swf</fix></code> the address <code><fix>http://example.com/swf/index.html</fix></code> will also be blocked.}}</p>
 
   <p>{{s14 Solution to this problem: add a pipe symbol to the filter to show that there should be definitely the end of the address at this point. For example the 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.html</fix></code>. And the filter <code>|http://baddomain.example/</code> will block <code>http://baddomain.example/banner.gif</code> but not <code>http://gooddomain.example/analyze?http://baddomain.example</code>.}}</p>
@@ skipping 195 matching lines @@
   <h3 id="elemhide_attributes">{{s93 Attribute selectors}}</h3>
 
   <p>{{s94 Some advertisers don't make it easy for you — their text advertisements have neither an id nor a class attribute. You can use other attributes to hide those, for example <code><fix>##table[width="80%"]</fix></code> will hide tables 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 the beginning and the end of an attribute, for example <code><fix>##div[title^="adv"][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 with width attribute set to 80% and bgcolor attribute set to white.}}</p>
 
   <h3 id="elemhide_css">{{s95 Advanced selectors}}</h3>
 
   <p>{{s97 In general, any CSS selector supported by Firefox can be used for element hiding. For example the following rule will hide anything following a div element 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-selectors/}}">W3C CSS specification</a> (note that not all selectors are supported by Firefox yet).}}</p>
 
   <p>{{s98 <em>Note</em>: This functionality is for advanced users only, you should be comfortable with CSS selectors to use it. Adblock Plus won't be able to check the syntax of the selector you are adding, if you use invalid CSS syntax you might break other (valid) rules you have. Check JavaScript Console for CSS errors.}}</p>
 
+<h3 id="elemhide-emulation">{{ elemhide-emulation-heading[heading] Extended CSS selectors (Adblock Plus specific) }}</h3>
+
+<p>
+  {{ elemhide-emulation-1 Sometimes the standard CSS selectors aren't powerful enough to hide an advertisement, for those cases we have added some new ones, namely <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). }}
+</p>
+<p>
+  {{ elemhide-emulation-2 When writing an element hiding filter that makes use of 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 those filters are specific to as few domains and elements as possible. }}
+</p>
+<h4>:-abp-properties()</h4>
+<p>
+  {{ abp-properties-1 <code><fix>:-abp-properties(properties)</fix></code> will select elements based upon stylesheet properties. For example <code><fix>:-abp-properties(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. }}
+</p>
+<p>
+  {{ 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 surrounding the properties expression with "/". For example, <code><fix>:-abp-properties(/width:30[2-8]px;height:250px;/)</fix></code> will match widths between 302 and 308 pixels and a height of 250 pixels. }}
+</p>
+<p>
+  {{ abp-properties-3 <em>Note</em>: The <a href="https://adblockplus.org/development-builds/new-css-property-filter-syntax">older syntax</a> for the CSS property filters is deprecated and will be automatically converted to the new format&nbsp;. The syntax to select the style properties remain the same. For example, <code><fix>[-abp-properties='width:300px;height:250px;']</fix></code> will be converted to <code><fix>:-abp-properties(width:300px;height:250px;)</fix></code>. }}
+</p>
+<h4>:-abp-has()</h4>
+<p>
+  {{ 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><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 inner selector can be relative to the element scope, and can use any of the pseudo-selectors, including <code><fix>:-abp-has()</fix></code> and will determine whether the selection will occur. }}
+</p>
+
 <h3 id="elemhide_exceptions">{{s99 Exception rules}}</h3>
 
 <p>
   {{s100 Exception rules can disable existing rules on particular domains.}} {{s101 These are mostly
   useful to filter subscription authors who are extending another filter subscription that they
   cannot change.}} {{s102 For example, the rule <code><fix>##div.textad</fix></code> can be
   disabled on <code><fix>example.com</fix></code> using the exception rule
   <code><fix>example.com#@#div.textad</fix></code>.}} {{s103 The combination of these two
   rules has exactly the same effect as the single rule
   <code><fix>~example.com##div.textad</fix></code>.}} {{s104 It is recommended that you use
   exception rules only when you cannot change an overly general element hiding rule, in all the
   other cases limiting this rule to the necessary domains is preferable.}}
-</p>
-
-<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 section before the element hiding
exception one.

I wonder if there's a better title we can use, the difference between "Element
hiding -> Advanced selectors" and "Element hiding -> Advanced element hiding"
seems like it would be kind of confusing.

Perhaps it would make more sense to the reader if we call the section "Advanced
pseudo-selectors" or something similar, and work backwards from there to explain
the that the "#?#" syntax is required for those and that the domain restriction
applies for them too? The structure might look something like this:

Advanced pseudo-selectors
  Introductory text explaining the idea, requirement to specify
  a domain, that they are slow etc.

  :-abp-has
  explanation of how that works, a few examples

  :-abp-properties
  explanation of how that works, a few examples

[hub, 2017/07/11 22:25:58]

make sense
 
ok

-
-<p>
-  {{elemhide-emulation-explanation-p1 Advanced hiding rules will hide elements that 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="#generic-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 CSS selector directly", how is
that different from regular element hiding?

Perhaps, add "For example" before your example filter?

Nit: "match" not "matches".

Nit: The colon after the "specific filters" link seems unnecessary.

I think the last sentence should also explain why it's forbidden to use this
syntax without a domain limitation.

-</p>
-<p>
-  {{elemhide-emulation-explanation-p2 <a href="#elemhide_exceptions">Exception rules</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.

-</p>
-<p>
-  {{elemhide-emulation-explanation-p3 Advanced hiding rules also introduce new pseudo-class selectors for when a plain CSS selector isn't enough. <code><fix>:-abp-has(selector)</fix></code> will select the element whose content match the enclosed selector. <code><fix>:-abp-properties(properties)</fix></code> will match elements based on their CSS style properties.}}
-</p>
-<p>
-  {{elemhide-emulation-explanation-p4 <code><fix>:-abp-properties(properties)</fix></code> will select elements based on properties of their stylesheet. For example, <code><fix>:-abp-properties(width:300px;height:250px;)</fix></code> will select elements that have <code><fix>width</fix></code> and <code><fix>height</fix></code> set to the specified values <code><fix>300px</fix></code> and <code><fix>250px</fix></code> respectively. The <a href="https://adblockplus.org/development-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 syntax 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 "For example".

I think you should break the part about the older syntax off into it's own
sentence and format it something like "Note: While the older syntax will
automatically be converted it has been deprecated." Maybe add a small example to
quickly show what the old syntax looks like too?

[hub, 2017/07/11 22:25:58]

Acknowledged.

-</p>
-<p>
-  {{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 direct 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 inner selector matching determine whether the selection occur. It is important that <code><fix>:-abp-has()</fix></code> be applied to a restricted number of elements 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 elements the :-abp-has applies
to could be moved into the introduction part which explains that these advanced
pseudo-selectors are slow? We could mention that they should be restricted to as
few domains and elements as possible at the same time.

[hub, 2017/07/11 22:25:58]

Acknowledged.

+  {{ exception-rules These exceptions will be applied to <a href="#elemhide-emulation">advanced pseudo-selector rules</a> as well. }}
 </p>
 
   <h3 id="elemhide_simplified">{{s105 Simplified element hiding syntax}}</h3>
 
   <p>{{s106 Adblock Plus supports simplified element hiding syntax (e.g. <code><fix>#div(id=foo)</fix></code>) for backwards compatibility only. Using this syntax is discouraged, usual CSS selectors are preferred. Support for this syntax might be removed at some point.}}</p>
 
   <h3 id="generic-specific">{{generic-specific-title Generic / Specific filters}}</h3>
 
   <p>{{generic-specific-explanation-p1 With the <code><fix>$generichide</fix></code> and <code><fix>$genericblock</fix></code> filter options the distinction between generic and specific filters becomes important.}}</p>
   <p>{{generic-specific-explanation-p2 We classify a filter to be <strong>specific</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 counts 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></code> and <code><fix>~example.com##div.textad</fix></code> are generic.}}</p>
@@ skipping 13 matching lines @@
   {{s110 The data used for creating the signature is a concatenated list of request variables (namely URI, host and user agent) separated by the <code><fix>NUL</fix></code> character "\0". For example:}}
 </p>
 
 <pre>
   /index.html?q=foo\0www.example.com\0Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:30.0) Gecko/20100101 Firefox/30.0
 </pre>
 
 <p>
   {{s111 Finally, generate the signature for this string by using the signature algorithm SEC_OID_ISO_SHA_WITH_RSA_SIGNATURE (default when using OpenSSL).}}
 </p>