How to write uBlock Filters

Post Reply
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

How to write uBlock Filters

Post by tong »

Filters
https://help.eyeo.com/adblockplus/how-to-write-filters
https://github.com/DandelionSprout/adfilt/blob/master/Wiki/SyntaxMeaningsThatAreActuallyHumanReadable.md
https://github.com/Sappurit/Sappurit-uBlock-Filters/blob/master/Filter_Basic.md
  • Network Filters (Simple blocking rules)
  • Cosmetic Filters (Hiding elements)
    • Type
      • Generic = Apply to all domains
      • Specific = Prefixed with the domain on which they are meant to apply
    • Method
      • Standard Cosmetic Filters = CSS Selector
      • Procedural Cosmetic Filters = Javascript code is used to find DOM elements

Code: Select all

Generic  -> Bad       ##body > div:has-text(Sponsored)
Specific -> Good      example.com##body > div:has-text(Sponsored)
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

CSS Selectors
https://www.w3.org/TR/selectors-3/#selectors
https://adblockplus.org/filter-cheatsheet

Code: Select all

example.com###advert                       matches the element with the unique id "advert"
example.com##.advert                       matches elements with the class "advert"
example.com##div[title="advert"]           matches all <div> elements with title attribute equal with "adv"
example.com##div[title="advert" i]         matches all <div> elements with title attribute equal with "adv" but case-insensitive
example.com##div[title^="adv"]             matches all <div> elements with title attribute begins with "adv"
example.com##div[title$="ert"]             matches all <div> elements with title attribute ends with "ert"
example.com##div[title*="ver"]             matches all <div> elements with title attribute contains the string "ver"
example.com##div[title~="advert"]          matches all <div> elements with title attribute "advert" in a list of whitespace-separated values
example.com##div[title|="advert"]          matches all <div> elements with title attribute "advert" followed by a hyphen -
example.com##div[width="80%"][size="7"]    matches multiple conditions
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

Extended CSS selectors (uBlock Origin Specific)
https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters

subject:not()
subject:has()
subject:has-text()
subject:matches-css()
subject:matches-css-before()
subject:matches-css-after()
subject:min-text-length()
subject:upward()
subject:watch-attr()
subject:xpath()
subject:nth-of-type(n)
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

CSS Combinators

Decendant Selector (whitespace) = Any child, any level
Child Combinator (>) = Direct child, first level only
Adjacent Sibling Combinator (+) = Next younger sibling only, same level, same parent
Following Sibling Combinator (~) = Any younger slibling, same level, same parent
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

Decendant Selector ( )

Any selector with white space between two selectors without a combinator. It will select any tags that are anywhere underneath (any level down, any deeper) of the parent tag in the markup structure.

Code: Select all

div span {}

<div>
  <span>Will be selected</span>
  <ul>
    <li>
       <span>Will be selected</span>
    </li>
  </ul>
</div>
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

Child Combinator (>)

> means it will only select tags that are direct children (direct descendant) of the parent tag. In otherwords, it only looks one level down the markup structure, no deeper.

Code: Select all

ol > li {}

<ol>
   <li>WILL be selected</li>
   <li>WILL be selected</li>
   <ul>
      <li>Will NOT be selected</li>
      <li>Will NOT be selected</li>
   </ul>
   <li>WILL be selected</li>
</ol>
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

Adjacent Sibling Combinator (+)

Select any tag that is directly follow after another tag (with nothing in between). Sibling selector the logic takes place within the same parent element. That’s what siblings means sharing the same parent.

Code: Select all

img + p {}

<div>
   <p>Will NOT be selected</p>
   <img />
   <p>Will be selected</p>
   <h2>...</h2>
   <p>Will NOT be selected</p>
</div>
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

General Sibling Combinator (~)

Sometime call as Following Sibling Combinator. Sibling means sharing the same parent. So the General Sibling Combinator means, The element being selected doesn’t need to immediately succeed the first element, but can appear anywhere after it in the same level.

Code: Select all

img ~ p {}

<div>
   <p>Will NOT be selected</p>
   <img />
   <p>Will be selected</p>
   <h2>...</h2>
   <p>Will be selected</p>
</div>
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

Procedural Cosmetic Filters by uBlock Origin
https://github.com/gorhill/uBlock/wiki/ ... ic-filters

Normal or standard cosmetic filters are declarative, i.e. they are used as selector in a CSS rule, and completely handled by browsers through style tag elements.

Procedural means javascript code is used to find DOM elements which must be hidden. A procedural cosmetic filter makes use of cosmetic filter operator, which will tell uBO how to find/filter DOM elements in order to find which DOM elements to target.

Procedural filters must always be specific, i.e. prefixed with the hostname of the site(s) on which they are meant to apply. If a procedural cosmetic filter is generic, i.e. meant to apply everywhere, it will be discarded by uBO.
tong
Site Admin
Posts: 2381
Joined: Fri 01 May 2009 8:55 pm

Re: CSS Selector

Post by tong »

How Element will be Selected

Code: Select all

example.com##table > tr > td:has-text(Sponsored)         Only <td> will be selected
example.com##table:has(> tr > td:has-text(Sponsored))    Full <table> will be selected
Post Reply