When scriptlets can receive extra optional paramaters, these will
now be passed as pair of extra paramaters in the filter declaration,
whereas each pair is a `name, value` instance.
As a result, the optional paramaters that can be passed to the
`aeld` scriptlet can be passed this way, i.e. no longer need
a JSON approach, example:
github.com##+js(aeld, click, , log, 1)
github.com##+js(aeld, , , runAt, idle, log, 1)
The non-optional paramaters are always positional, after which
the optional paramaters are non-positional pairs of values.
Alias: `trusted-set`
Behaves exactly like set-constant, except that any arbitrary JSON-
compatible value can be set.
By default the value is treated as a string, which can be anything.
If the value starts with `{` and ends with `}`, the value will be
JSON-parsed, and the `value` property of the resulting object will
be used.
As with any scriptlet requiring trust, filters using
`trusted-set-constant` can only come from trusted filter lists,
otherwise they are discarded.
Related discussion:
- https://github.com/uBlockOrigin/uAssets/discussions/18185#discussioncomment-5977456
This reflects the _world_ of the MV3 scripting API:
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/ExecutionWorld
MAIN: page's world
ISOLATED: extension's content script world
Some scriptlets are best executed in either world, so this
commit allows to pick in which world a scriptlet should execute
(default to MAIN).
For instance, the new sed.js scriptlet will now execute in
the ISOLATED world.
Related commit:
- 41876336db
The `tryCount` parameter has been removed.
The new default behavior of the sed.js scriptlet is to bail out
when the document itself has been fully loaded, i.e. when
DOMContentLoaded event is fired.
Two new parameters have been added to override the default quit out
behavior:
`stay, 1`
Use to force the scriptlet to stay at work forever.
`quitAfter, ms`
This tells the scriptlet to quit `ms` milliseconds after the
page has been loaded, i.e. after the DOMContentLoaded event has
been fired.
The mutation observer of the sed.js scriptlet can be a significant
overhead for pages with dynamically updated DOM, and in most cases
the scriptlet is useful only for DOM changes occurring before the
DOMContentLoaded event, so the default is to quit out when that
event is received ("quit out" means discarding the mutation observer
and having the scriptlet garbage-collected by the JS engine).
To ensure smooth transition in next stable release: people on
an older version of uBO could end up updating assets.json,
hence we needs to keep a local URL to the non-minified packaged
version of the lists.
At the moment, the only filter lists deemed from a "trusted source"
are uBO-specific filter lists (i.e. "uBlock filters -- ..."), and
the user's own filters from "My filters".
A new scriptlet which can only be used by filter lists from trusted
sources has been introduced: `sed.js`.
The new `sed.js` scriptlet provides the ability to perform
text-level substitutions. Usage:
example.org##+js(sed, nodeName, pattern, replacement, ...)
`nodeName`
The name of the node for which the text content must be substituted.
Valid node names can be found at:
https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName
`pattern`
A string or regex to find in the text content of the node as the target of
substitution.
`replacement`
The replacement text. Can be omitted if the goal is to delete the text which
matches the pattern. Cannot be omitted if extra pairs of parameters have to be
used (see below).
Optionally, extra pairs of parameters to modify the behavior of the scriptlet:
`condition, pattern`
A string or regex which must be found in the text content of the node
in order for the substitution to occur.
`sedCount, n`
This will cause the scriptlet to stop after n instances of substitution. Since
a mutation oberver is used by the scriptlet, it's advised to stop it whenever
it becomes pointless. Default to zero, which means the scriptlet never stops.
`tryCount, n`
This will cause the scriptlet to stop after n instances of mutation observer
run (regardless of whether a substitution occurred). Default to zero, which
means the scriptlet never stops.
`log, 1`
This will cause the scriptlet to output information at the console, useful as
a debugging tool for filter authors. The logging ability is supported only
in the dev build of uBO.
Examples of usage:
example.com##+js(sed, script, /devtoolsDetector\.launch\(\)\;/, , sedCount, 1)
example.com##+js(sed, #text, /^Advertisement$/)
