Advanced reference · Advanced
Page fixes and scriptlets
Understand packaged page fixes and the scriptlet grammar. Shield AdBlock 1.0.2 does not execute that grammar from added lists or custom rules.
Overview
Page Fixes use small helpers packaged with Shield to change narrowly defined page behavior. A filter can select a supported helper and its arguments; it cannot supply new JavaScript code for Shield to download and run.
The Page Fixes switch controls built-in fixes. Those bundled fixes remain a separate setting and still use the helpers packaged with Shield. Shield AdBlock 1.0.2 packages omit Fixes from Added Sources and scriptlets from rules you write, on Chrome, Edge and Firefox. Advanced Settings can reveal advanced controls; revealing them does not add that omitted tier.
These 1.0.2 packages contain the built-in fixes and omit the added-list and custom-rule scriptlet tier. Content embedded from other websites may remain unaffected, even when a built-in fix works on the main page.
Syntax
The examples in this guide show filter grammar. They are not executable added-list or custom-rule scriptlets in Shield AdBlock 1.0.2 packages. Bundled Page Fixes continue to use the packaged helpers when that setting is on.
Use a host-scoped form such as:
news.example##+js(set-constant, adBlockDetected, false)
This requests the packaged set-constant helper for that website. It is not JavaScript source, CSS, or a guarantee that the site uses that property. Arguments are comma-separated; an escaped comma is literal, and one matching outer quote layer is removed.
Current helper inventory
This build recognizes the following ten canonical names. The argument ranges exclude the helper name. The examples show the invocation inside +js(...); prefix each with a deliberate website scope, such as news.example##.
Scroll sideways to read the whole table.
| Helper and aliases | Purpose and arguments | Example | Expected effect and limits |
|---|---|---|---|
set-constant; set |
Set a dotted property to one allowed value; exactly 2 arguments. | +js(set-constant, adBlockDetected, false) |
Installs the supported constant behavior. Arbitrary strings, code and unbounded numbers are rejected. |
abort-current-script; acs, abort-current-inline-script, acis |
Stop a current script on a property access; property plus optional content and source needles, 1–3 arguments. | +js(abort-current-script, adblock) |
Acts on matching script access, not every script on the page. Needles must be literals. |
abort-on-property-read; aopr |
Stop code when it reads a property; exactly 1 argument. | +js(abort-on-property-read, adblock) |
Affects the named property chain, which must be a plain dotted identifier path. |
abort-on-property-write; aopw |
Stop code when it writes a property; exactly 1 argument. | +js(abort-on-property-write, antiAdblock.write) |
Targets that property chain; it can break legitimate code that writes there. |
prevent-addEventListener; aeld, addEventListener-defuser |
Prevent matching listener registration; event and handler-source literals, exactly 2 arguments. | +js(prevent-addEventListener, click, antiAdblock) |
Both conditions must match. Empty or ! predicates cannot make the entire request unconditional; regex and extra upstream options are rejected. |
prevent-fetch; no-fetch-if |
Prevent matching page fetches; condition plus optional response token, 1–2 arguments. | +js(prevent-fetch, url:ads method:POST, emptyObj) |
Matches all supplied literal conditions and supplies the selected empty response. It does not cancel every browser-level request type. |
prevent-xhr; no-xhr-if |
Prevent matching XMLHttpRequests; condition plus optional response token, 1–2 arguments. | +js(prevent-xhr, url:collect method:POST, emptyArr) |
Uses URL and method predicates; fetch-only mode: conditions are rejected. |
json-prune |
Remove JSON properties; prune paths plus optional required paths, 1–2 arguments. | +js(json-prune, payload.secret, payload.ready) |
Prunes a matching JSON structure when its required paths exist. This is a bounded path language, not arbitrary JSONPath. |
prevent-window-open; nowoif, no-window-open-if, window.open-defuser |
Prevent matching window.open calls; 0–1 literal argument. |
+js(prevent-window-open) |
With no predicate, prevents calls in its eligible scope. Literal matching can inspect the joined call arguments, not only the URL; replacement and delay options are rejected. |
prevent-setTimeout; nostif, no-setTimeout-if, setTimeout-defuser |
Prevent matching timers; optional callback needle and optional delay, 0–2 arguments. | +js(prevent-setTimeout, adRefresh, 1000) |
Matches the callback text and supplied delay. A delay must be finite; regex arguments and extra options are rejected. |
Canonical names and aliases may also carry a .js suffix. Prefer canonical names in new rules so the intent is easier to read.
Argument boundaries
Property helpers accept dotted identifiers, not bracket expressions, function calls or prototype-reaching chains. set-constant accepts the named values undefined, false, true, null, noopFunc, trueFunc, falseFunc, noopPromiseResolve, noopPromiseReject, emptyObj and emptyArr, the supported empty forms, and integers from −32767 through 32767.
Request helpers accept bounded whitespace-separated literal conditions. The field names are url, method, and, for fetch only, mode. A bare condition is a URL substring. Negation is available with !; all predicates must match. Response tokens are the default empty text, emptyStr, emptyObj and emptyArr. Unknown fields or response tokens are rejected.
JSON pruning uses whitespace-separated dotted paths. Its bounded segments can include the supported *, [], [-] and {-} forms, with restrictions on position and work. Prototype-reaching paths are rejected. Prefer a simple named path unless you have checked the exact nested structure and desired effect.
Limits
A scriptlet name being recognized is not enough for a rule to run. Its arity, argument grammar, website scope and switches must qualify, and the package must include that tier. Shield AdBlock 1.0.2 packages omit added-list and custom-rule scriptlets, so a rule that matches this grammar is not executed from a list you added or a rule you wrote. Regex arguments, unknown names and unsupported extra options cause the whole rule to be skipped. AdGuard #%# scriptlet syntax is not accepted as a substitute for ##+js(...).
Built-in fixes have their own eligibility and registration state. A successful configuration or registration does not prove that a helper ran, intercepted the intended call, or removed a visible ad. No helper guarantees YouTube ad removal or compatibility with every version of another blocker’s scriptlets.
Examples
To disable a named helper on a site, use a scriptlet exception:
news.example#@#+js(set-constant)
The name-only exception disables that helper in the matching scope. news.example#@#+js() is the broader all-scriptlets exception. These do not disable network or cosmetic rules. Review exceptions as carefully as invocations and reload the website after changes.