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>
@@ skipping 215 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-title Advanced pseudo-selectors}}</h3>

[kzar, 2017/07/13 11:37:18]

After discussing in IRC I think "Extended CSS Selectors (ABP-specific)" would be
a better title.

[hub, 2017/07/13 20:17:34]

Acknowledged.

+
+<p>
+  {{elemhide-emulation-explanation-p1 Sometime CSS selectors aren't enough to chose items. In certain circumstances examining the content of an element is required, and this is why we have added the advanced pseudo-selector <code><fix>:-abp-has()</fix></code> and <code><fix>:-abp-properties()</fix></code>. The filter rule <code><fix>example.com#?#selector</fix></code> will hide elements matching the selector.}}

[kzar, 2017/07/13 11:37:18]

How about this for the first two paragraphs?

"Sometimes the standard CSS selectors aren't powerful enough to hide an
advertisement, for those cases we have added some new ones, namely :-abp-has()
and :-abp-properties().

When writing an element hiding filter that makes use of these extended selectors
you must use the #?# syntax, e.g. example.com#?#selector . 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."

[hub, 2017/07/13 20:17:34]

Acknowledged.

+</p>
+<p>
+  {{elemhide-emulation-explanation-p2 In order to minimise the performance impact, it is important to restrict with a proper CSS selector the number of elements these pseudo-selectors apply to. These filters only exist as <a href="#generic-specific">specific filters</a>, a domain is mandatory.}}
+</p>
+<p>{{elemhide-emulation-explanation-p3 <em>Note</em>: You can also use these filter rules for a regular CSS selector. They might work better in certain situations.}}

[kzar, 2017/07/13 11:37:18]

I think we should remove this note, it relates to an implementation detail which
could change in the future.

[hub, 2017/07/13 20:17:34]

Done.

+</p>
+<h4>{{abp-properties-title :-abp-properties()}}</h4>
+<p>
+  {{abp-properties-explanation-p1 <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.}}

[kzar, 2017/07/13 11:37:18]

I guess the explanation of the example here is not quite right, since we don't
select elements which have a style property that specify that width and height?
How about something like this:

"... will select elements that have a corresponding CSS rule in a stylesheet
which sets the width and height to the values 300px and 250px respectively."

[kzar, 2017/07/13 11:37:18]

Maybe mention how the properties are matched case-insensitively, wildcards can
be used and regular expression matching?

https://adblockplus.org/development-builds/css-property-matching-improvements

[hub, 2017/07/13 20:17:34]

Done.

+</p>
+<p>
+  {{abp-properties-explanation-p2 <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-title :-abp-has()}}</h4>
+<p>
+  {{abp-has-explanation-p1 <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 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.}}
+  {{exception-rules-p6 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>