Writing Adblock Plus filters

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.

Disclaimer: All filter examples given here are really only examples and are not meant to be used.

Introduction to Adblock Plus filters

The options described in this section should be enough for users who have to create a filter occasionally.

Basic filter rules

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 http://example.com/ads/banner123.gif where 123 is a random number. Here blocking the complete address won’t help you, you need a more general filter — like http://example.com/ads/banner*.gif. Or maybe even http://example.com/ads/*.

Note: Make sure that you are not replacing too much by wildcards. The filter http://example.com/* will definitely block all banners but it will also block everything else from example.com that you still might want to see.

Defining exception rules

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.

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 adv blocking http://example.com/advice.html, you can define an exception rule @@advice. Exception rules are no different from filter rules, you can use wildcards or regular expressions. You only have to precede them by @@ to indicate an exception rule.

Exception rules can do more. If an exception rule starts with http:// or https:// (optionally with a pipe before it) it will make whole pages an exception. For example, if your exception rule is @@|http://example.com and you open some page from example.com — Adblock Plus will be entirely disabled on this page and nothing will be blocked.

Comments

Any rule that starts with an exclamation mark is considered a comment. It will still show up in the filter list but in grey instead of black. Adblock Plus will ignore this rule for actual blocking so it is safe to write there whatever you want. You can place a comment rule above a real filter to describe what it is doing. Or you can put a comment on top of your filter list stating your authorship (actually most filter list authors do).

Advanced features

The features described in this section are usually used only by power users and filterlist creators. Feel free to skip it.

Matching at beginning/end of an address

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 ad and *ad*. 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 swf the address http://example.com/swf/index.html will also be blocked.

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 swf| will block http://example.com/annoyingflash.swf but not http://example.com/swf/index.html. And the filter |http://baddomain.example/ will block http://baddomain.example/banner.gif but not http://gooddomain.example/analyze?http://baddomain.example.

Specifying filter options

Adblock Plus allows you to specify a number of options to modify the behavior of a filter. You list these options separated with commas after a dollar sign ($) at the end of the filter, for example:

*/ads/*$script,match-case

Here */ads/* is the actual filter and script and match-case are its options. Currently the following options are supported:

Type options: determine which types of elements a filter can block (or whitelist in case of an exception rule). Multiple type options can be specified to indicate that the filter should be applied to several types of elements. Possible types are:
- script — external scripts loaded via HTML script tag
- image — regular images, typically loaded via HTML img tag
- background — background images, often specified via CSS
- stylesheet — external CSS stylesheet files
- object — content handled by browser plugins, e.g. Flash or Java
- xbl — XBL bindings (typically loaded by -moz-binding CSS property) Firefox 3 or higher required
- ping — link pings Firefox 3 or higher required
- xmlhttprequest — requests started by the XMLHttpRequest object Firefox 3 or higher required
- object-subrequest — requests started plugins like Flash Firefox 3 or higher required
- dtd — DTD files loaded by XML documents Firefox 3 or higher required
- subdocument — embedded pages, usually included via HTML frames
- document — the page itself (only exception rules can be applied to the page)
- other — types of requests not covered in the list above (in Firefox 2 this includes XBL bindings and XMLHttpRequests as well)
Inverse type options: specify the element types the filter should not be applied to. Possible inverse type options: ~script, ~image, ~background, ~stylesheet, ~object, ~xbl, ~ping, ~xmlhttprequest, ~object-subrequest, ~dtd, ~subdocument, ~document, ~other
match-case — makes the filter only apply to addresses with matching letter case, e.g. the filter */BannerAd.gif$match-case will block http://example.com/BannerAd.gif but not http://example.com/bannerad.gif.
collapse — this option will override the global “Collapse blocked elements” and make sure the filter always collapses the element. Similarly the ~collapse option will make sure the filter never collapses the element.

Using regular expressions

If you want even more control about what your filters match and what they don’t match, you can use regular expressions. For example the filter /banner\d+/ will match banner123 and banner321 but not banners. You can check out documentation on regular expressions to learn how to write them.

Note: You should not use regular expressions to speed up processing of your filter list. You might hear this advice often but it is outdated — starting with Adblock Plus 0.7 basic filters are actually processed faster than regular expressions.

Element hiding: basic rules

Sometimes you will find advertisements that can’t be blocked because they are embedded as text in the web page itself. If you look at the source code of the web page you might find something like this:

<div class="textad">
Cheapest tofu, only here and now!
<div>
<div id="sponsorad">
Really cheap tofu, click here!
<div>
<textad>
Only here you get the best tofu!
</textad>

You need to download the web page so you will necessarily download the advertisements. All you can do here is to hide the advertisement so you don’t need to see it. That’s what element hiding is meant for.

The first advertisement above is contained inside a div element with class attribute “textad”. The following rule will hide exactly this combination: #div(textad). You can hide elements by their id attribute in the same way, #div(sponsorad) will hide the second advertisement. You don’t need to specify the element name, the rule #*(sponsorad) will work just as well. And you can hide elements by element name only, e.g. #textad for the third advertisement.

So, how do you know what to put into your element hiding rule? You have two choices: either you dig into source code of the web page and try to locate the advertisement there, or you use DOM Inspector (Firefox users have to choose “Custom install” and check “Development Tools” when installing Firefox to install DOM Inspector as well). Basic HTML knowledge is useful in both cases.

Note: Element hiding works very differently from normal filters. This has the implication that no wildcards are supported in element hiding rules, hit count for them won’t be available and exception rules will be ignored.

Element hiding: limiting rules to certain domains

Usually you want to hide a specific ad on one specific site, you don’t want your rule to be applied on other sites. For example the rule #*(sponsor) might hide valid code on some sites. But if you write it as example.com#*(sponsor) it will be applied on http://example.com/ and http://something.example.com/ but not on http://example.org/. You can also specify multiple domains — simply separate them with commas: domain1.example,domain2.example,domain3.example#*(sponsor).

Note: Due to the way how element hiding is implemented, you really can only limit it to full domain names. You cannot use any other part of the address and you cannot use domain as a replacement for domain.example,domain.test.

Note: Element hiding rules with domain limitation can be used to hide browser’s user interface elements as well. For example the filter rule browser#menuitem(javascriptConsole) will hide the JavaScript Console entry in Firefox’s Tools menu.

Element hiding: attribute selectors

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 #table(width=80%) will hide tables with width attribute set to 80%. If you don’t want to specify the full value of the attribute, #div(title*=adv) 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 #div(title^=adv)(title$=ert) will hide div elements with title starting with “adv” and ending with “ert”. As you see, you can also use multiple conditions — table(width=80%)(bgcolor=white) will match tables with width attribute set to 80% and bgcolor attribute set to white.

Element hiding: using raw CSS

If even selecting elements by any attribute isn’t enough, you can use the full power of CSS selectors. For example the following rule will hide anything following a div element with class “adheader”: ##div.adheader + *. The two hashes indicate that this element hiding rule is to be interpreted as a CSS selector (this particular one is a adjacent sibling selector).

Note: 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.

Compatibility notes (Adblock and different Adblock Plus versions)

This document describes the choices you have with Adblock Plus 0.7. However, if you are assembling a filter list that you wish to share, you might want to consider other Adblock Plus versions and Adblock as well. I will give a short overview of differences you will find in those:

Matching at beginning/end of an address: is only supported in Adblock Plus 0.6.1.2 and higher
Exception rules: in Adblock 0.5 and Adblock Plus 0.5 exception rules preceded with will only work for single items but not complete pages. Exceptions for complete pages are defined differently. Note that first Adblock version to support exception rules is 0.5.3.40.
Comments: Adblock 0.5 and Adblock Plus before 0.7 will interpret them as real rules. This didn’t stop filter list authors from using them, chances of these rules actually matching anything are very low.
Filter options: are only supported in Adblock Plus 0.7.1 and higher.
Element hiding: was introduced in Adblock Plus 0.6.1 where only the basic rules were supported. Attribute selectors, raw CSS and limiting rules to a domain came with Adblock Plus 0.7. Adblock Plus 0.5 had a feature called “DIV blocking” that was used for the same purpose. While the syntax is (intentionally) similar, the implementation is entirely different. For that reason there is no easy way to translate DIV blocking rules into element hiding rules or back.