Snippet filters tutorial

This guide is aimed at filter authors and advanced users that want to make the most out of Adblock Plus. It's a companion to the guide on writing filters that covers snippet filters. While it's recommended that you be familiar with writing filters, you should be OK otherwise. You don't need a deep knowledge of JavaScript, but you need to be familiar with it, as well as with web technologies like HTML, CSS, and the DOM. If you really want, Mozilla has a great resource to learn JavaScript, HTML and CSS

This guide doesn't cover how to write an actual snippet, i.e. the JavaScript code that is loaded by Adblock Plus into the browser when you execute a snippet filter. This requires modifying the extension, and it will be covered in an upcoming developer guide.

Table of contents

What are snippet filters?

Snippet filters are a new type of filter introduced in Adblock Plus 3.3 that allows running specialized code snippets (written in JavaScript) on pages within a list of specified domains. These snippets are selected from an existing library available in Adblock Plus.

The snippet approach allows interfering with ad display code in a more efficient manner, and also allows locating elements to hide in a way that can't be expressed with CSS or the current advanced selectors.

Syntax

The basic syntax of a snippet filter is as follows:

export_window.png

You can run several snippets in the same filter by separating them with a ;. See example 6.

Arguments

Arguments are strings. They can be surrounded by single quotes (') if they contain spaces. To have a single quote ' as part of the argument, escape it like this: \' ; you can also escape spaces with \ instead of quoting the argument. See examples 3a3b and 3c.

You can input Unicode characters by using the syntax \uNNNN, where NNNN is the Unicode codepoint. See example 4.

You can also input carriage return, line feed, and tabs using \r\n, and \t, respectively. To have a \ in an argument, including a regular expression, it must be escaped with \, i.e. doubled up. See example 5.

Examples

Basic snippet filter syntax

These examples demonstrate the syntax of a snippet filter and how to pass arguments. While we mostly use the log snippet, these examples apply to other snippet functions as well.

Example 1

example.com#$#log Hello

This prints "Hello" in the web console on the domain example.com and its subdomains.

Example 2

anotherexample.com,example.com#$#log Hello

Same as example 1, but "Hello" also appears on the domain anotherexample.com. Like with other filter types, multiple domains should be separated by commas ,.

This filter makes the filter in example 1 obsolete. Having both filters makes the message appear twice on example.com, as both would be run.

Example 3a

example.net,example.com#$#log 'Hello from an example to another example'

This is a different message from example 2. Because it contains spaces, the string must be surrounded with single quotes '.

Example 3b

example.net,example.com#$#log 'Hello it\'s me again'

This shows the escape sequence for having a single quote, using \'.

Example 3c

example.net,example.com#$#log Hello\ no\ quotes

You can also escape spaces instead of quoting the argument, using \.

Example 4

emoji.example.com#$#log \u1F601

On the domain emoji.example.com, the emoji 😀 is printed in the console. The filter will not be run on example.com or www.example.com. This shows how to use escape for Unicode symbols.

Example 5

emoji.example.com#$#log '\u1F601\nand a new line'

This is similar to example 4, except that the filter prints the emoji 😀 and then on a new line, prints and a new line. This shows how to use escape for Unicode symbols, as well as adding a new line.

Example 6

Running two snippets:

debug.example.com#$#debug; log 'This should be prefixed by DEBUG'

First, we see debug. This is the snippet that enables debugging. It's just like any other snippet. Then we see log, whose output is modified when debugging is enabled. See the section on debugging for more details.

example.com#$#log 'Always log'; log 'And better twice than once'

This is another example of logging two lines. Here the snippet command will be called twice.

Debugging

We saw a debug snippet in Example 6. Its use is simple: calling debug before a snippet turns on the debug flag. If the other snippets support it, they'll enable their debug mode. What a snippet does in debug mode is up to the snippet.

debug

Since: Adblock Plus 3.8

Enables debug mode.

Filter

Result

debug; log OK

logs OK to the console with a preceded by a DEBUG word

debug; abort-on-property-read atob

activates debug mode for the abort-on-property-read snippet

log

Since: Adblock Plus 3.3

Logs its arguments to the console. This may be used for testing and debugging.

Filter

Result

log OK

logs OK to the console

log Hello, world!

logs Hello, World! to the console (with 2 parameters)

log 'Hello, world!'

logs Hello, World! to the console (with 1 parameter)

trace

Since: Adblock Plus 3.3

Similar to log, but does the logging in the context of the document rather than the content script.

This may be used for testing and debugging, especially to verify that the injection of snippets into the document is working without any errors.

Filter

Result

trace OK

logs OK to the console

trace Hello, world!

logs Hello, World! to the console (with 2 parameters)

trace 'Hello, world!'

logs Hello, World! to the console (with 1 parameter)

Behavioral Snippets

Snippets that change the normal execution behavior of the page. 

abort-current-inline-script

Since: Adblock Plus 3.4.3

Aborts the execution of an inline script when a property is either read or written.

Name

Description

Mandatory

api

API function or property name to anchor on. It can also be the path to that property.

If the property is a direct child of window, this parameter will be just the property name. But, if you want to access a sub property, this parameter will be a chain of properties separated by dots.

yes

search

If specified, only scripts containing the given string are prevented from executing. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

no

abort-on-property-read

Since: Adblock Plus 3.4.1

Patches a property on the window object to abort execution when the property is read.

No error is printed to the console.

The idea originates from uBlock Origin.

Name

Description

property

The name of the property or the path to that property. If the property is a direct child of window, this parameter will be just the property name. But, if you want to access a sub property, this parameter will be a chain of properties separated by dots.

abort-on-property-write

Since: Adblock Plus 3.4.3

Patches a property on the window object to abort execution when the property is written.

No error is printed to the console.

The idea originates from uBlock Origin.

Name

Description

property

The name of the property or the path to that property. If the property is a direct child of window, this parameter will be just the property name. But, if you want to access a sub property, this parameter will be a chain of properties separated by dots.

abort-on-iframe-property-read

Since: Adblock Plus 3.10.1

Patches a list of properties on the iframes' window object to abort execution when the property is read.

No error is printed to the console.

Name

Description

properties

The list with the properties we want to abort on.

abort-on-iframe-property-write

Since: Adblock Plus 3.10.1

Patches a list of properties on the iframes' window object to abort execution when the property is written.

No error is printed to the console.

Name

Description

properties

The list with the properties we want to abort on.

cookie-remover

A snippet to remove certain cookies.

Name

Description

Mandatory

cookie

Pattern that matches the name of the cookie(s) we want to remove. If the string starts and ends with a slash (/), the text in between is treated as a regular expression.

yes

freeze-element

Since: Adblock Plus 3.10

Freezes a DOM element so it prevents adding new nodes inside it.

Name

Description

Example

Mandatory

selector

The CSS selector for the parent element that we want to freeze

'.left-content .container'

yes

options

A single parameter for snippet's options. A string containing all the options we want to pass, each of them separated by a plus character (+). Empty single quotes if none ('')

Available options:

•subtree (if we want to freeze all the element's children as well)

•abort (throw an error every time an child element gets added)

'' or subtree or abort or subtree+abort etc.

no

exceptions

An array of regex/selectors used to specify the nodes we don't want to prevent being added. Each array item can be:

•selector (targeting Element nodes)

•regex (targeting Text nodes, identified by slash)

.article #banner .navigation /.*/

no

json-overrride

It's very similar to json-prune, but instead of removing a property, we override it with a value from the same list as for override-property-read.

Name

Description

Mandatory

rawOverridePaths

A list of space-separated properties to remove. It also accepts property chains - e.g. foo.bar.tar.

yes

value

The value to override the property with (see below for possible values)

yes

rawNeedlePaths

A list of space-separated properties which must be all present for the pruning to occur. It also accepts property chains.

no

filter

A string to look for in the raw string, before it's passed to JSON.parse.

If no match is found no further search is done on the resulting object.

If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

no

json-prune

Since: Adblock Plus 3.9.0

Traps calls to JSON.parse, and if the result of the parsing is an Object, it will remove specified properties from the result before returning to the caller.

The idea originates from uBlock Origin.

Name

Description

Mandatory

rawPrunePaths

A list of space-separated properties to remove.

yes

rawNeedlePaths

A list of space-separated properties which must be all present for the pruning to occur.

no

override-property-read

Since: Adblock Plus 3.9.4

Overrides a property's value on the window object with a set of available properties.

The idea originates from uBlock Origin.

Name

Description

property

The name of the property or the path to that property. If the property is a direct child of window, this parameter will be just the property name. But, if you want to access a sub property, this parameter will be a chain of properties separated by dots.

value

The value to override the property with.

prevent-listener

Prevents adding event listeners.

Wrap EventTarget.prototype.addEventListener and don't allow adding listeners for certain types of events.

Name

Description

Mandatory

type

Pattern that matches the type(s) of event we want to prevent. If the string starts and ends with a slash (/), the text in between is treated as a regular expression.

yes

handler

Pattern that matches the event handler's declaration. If the string starts and ends with a slash (/), the text in between is treated as a regular expression.

no

selector

The CSS selector that the event target must match. If the event target is not an HTML element the event handler is added.

no

simulate-event-poc

Triggers an event handler or a combination of those.

Name

Description

Mandatory

event

The event we want to dispatch.

yes

selector

The CSS/Xpath selector that an HTML element must match for the event to be triggered.

yes

delay

The delay between the moment when the node is inserted and the moment when the event is dispatched.

no

simulate-mouse-event

Triggers arbitrary mouse events on elements that are matched by a CSS or Xpath selector, by calling dispatchEvent for a selector.

Name

Description

Mandatory

selectors

The CSS/Xpath selector that an HTML element must match for the event to be triggered. Maximum 7 selectors are supported. Take a look at the optional parameters and the examples below for the explanation of how they should be written.

yes

Optional parameters are added to the selectors with a $ sign. Multiple parameters can be combined for a single selector by separating them with a comma. If a parameter is not specified, the default value will be assumed for that selector.

Name

Description

Default

Mandatory

$trigger

If this flag is not set, only the chosen event for the last selector will be triggered. $trigger flag can be used for the other selectors to make sure the event is triggered for them as well. $trigger is always true for the last selector so can be omitted for it.

false

no

$delay

Determines how much time the snippet should wait before simulating the even. Note that the default is 500 ms. If you don't want to have a delay (same as in simulate-event-poc), you should explicitly state $delay=0.

500

no

$continue

If set, the event will be triggered after each delay period ends. For example, if the selected event is click and the delay is 500 ms. The click event will be triggered every 500 ms instead of just once.

false

no

$event

Determines which event should be simulated for the selector.

click

no

strip-fetch-query-parameter

Since: Adblock Plus 3.5.1

Strips a query string parameter from fetch() calls.

Name

Description

Mandatory

name

The name of the parameter.

yes

urlPattern

An optional pattern that the URL must match. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

no

Conditional Hiding Snippets

Snippets that are responsible for hiding page content based on various conditions, such as matching text, image, style, graph, etc.

hide-if-contains

Since: Adblock Plus 3.3

Hides any HTML element or one of its ancestors matching a CSS selector if the text content of the element contains a given string.

Name

Description

Mandatory

search

The string to look for in HTML elements. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

yes

selector

The CSS selector that an HTML element must match for it to be hidden.

yes

searchSelector

The CSS selector that an HTML element containing the given string must match. Defaults to the value of the selector argument.

no

hide-if-contains-image

Since: Adblock Plus 3.4.2

Hides any HTML element or one of its ancestors matching a CSS selector if the background image of the element matches a given pattern.

Name

Description

Mandatory

search

The pattern to look for in the background images of HTML elements. This must be the hexadecimal representation of the image data for which to look. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

yes

selector

The CSS selector that an HTML element must match for it to be hidden.

yes

searchSelector

The CSS selector that an HTML element containing the given pattern must match. Defaults to the value of the selector argument.

no

hide-if-contains-similar-text

Hides an element based on its similar text content.

hide-if-contains-similar-text currently uses a pre-sorted Levenshtein distance for cases where the content has shuffled chars or text.

Name

Description

Mandatory

search

The string to match to the similar text. Is considered similar text that isn't hidden by CSS properties or other means. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

yes

selector

The CSS selector that an HTML element must match for it to be hidden.

yes

searchSelector

The CSS selector that an HTML element containing the given string must match. Defaults to the value of the selector argument.

no

hide-if-contains-visible-text

Since: Adblock Plus 3.6

Hides any HTML element matching a CSS selector if the visible text content of the element contains a given string.

Name

Description

Mandatory

search

The string to match to the visible text. Is considered visible text that isn't hidden by CSS properties or other means. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

yes

selector

The CSS selector that an HTML element must match for it to be hidden.

yes

searchSelector

The CSS selector that an HTML element containing the given string must match. Defaults to the value of the selector argument.

no

hide-if-contains-and-matches-style

Since: Adblock Plus 3.3.2

Hides any HTML element or one of its ancestors matching a CSS selector if the text content of the element contains a given string and, optionally, if the element's computed style contains a given string.

Name

Description

Mandatory

search

The string to look for in HTML elements. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

yes

selector

The CSS selector that an HTML element must match for it to be hidden.

yes

searchSelector

The CSS selector that an HTML element containing the given string must match. Defaults to the value of the selector argument.

no

style

The string that the computed style of an HTML element matching selector must contain. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

no

searchStyle

The string that the computed style of an HTML element matching searchSelector must contain. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

no

hide-if-graph-matches

Since: Adblock Plus 3.8

Hides any HTML element if its structure (graph) is classified as an ad by a built-in machine learning model.

Name

Description

Mandatory

selector

A selector that produces a list of targets to hide.

yes

tagName

An optional selector for a child element of 'selector' to run inference on.

yes

hide-if-has-and-matches-style

Since: Adblock Plus 3.4.2

Hides any HTML element or one of its ancestors matching a CSS selector if a descendant of the element matches a given CSS selector and, optionally, if the element's computed style contains a given string.

Name

Description

Mandatory

search

The CSS selector against which to match the descendants of HTML elements.

yes

selector

The CSS selector that an HTML element must match for it to be hidden.

yes

searchSelector

The CSS selector that an HTML element containing the specified descendants must match. Defaults to the value of the selector argument.

no

style

The string that the computed style of an HTML element matching selector must contain. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

no

searchStyle

The string that the computed style of an HTML element matching searchSelector must contain. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

no

hide-if-labelled-by

Since: Adblock Plus 3.9

Hides any HTML element that uses an aria-labelledby, or one of its ancestors, if the related aria element contains the searched text.

Name

Description

Mandatory

search

The string to look for in HTML elements. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

yes

selector

The CSS selector of an HTML element that uses as aria-labelledby attribute.

yes

searchSelector

The CSS selector of an ancestor of the HTML element that uses as aria-labelledby attribute. Defaults to the value of the selector argument.

no

hide-if-matches-xpath

Since: Adblock Plus 3.9.0

Hide a specific element through a XPath 1.0 query string. See Getting started with XPath filters to know more.

Name

Description

Mandatory

query

The XPath query that targets the element to hide.

yes

hide-if-shadow-contains

Hides any HTML element or one of its ancestors matching a CSS selector if the text content of the element's shadow contains a given string.

Name

Description

Mandatory

search

The string to look for in every HTML element's shadow. If the string begins and ends with a slash (/), the text in between is treated as a regular expression.

yes

selector

The CSS selector that an HTML element must match for it to be hidden.

yes

 

 

 

Was this article helpful?
1 out of 2 found this helpful