Dashboard: Develop - uBlockOrigin/uBOL-home GitHub Wiki

The Develop pane is meant for technical users.

Non-technical users should avoid tampering with features requiring advanced knowledge about the inner workings of a browser, and more specifically about the DNR API. Misusing the tools available in the Develop pane could cause harm to your privacy and security.

The Develop pane becomes available when "Developer mode" setting is enabled in the Settings pane. It is disabled by default. Administrators can prevent "Developer mode" from being enabled by adding develop token to managed disabledFeatures setting.

---

Custom DNR rules

You can create custom DNR rules through a (CodeMirror-based) editor.

Do not add DNR rules from untrusted sources

For the sake of convenience, the DNR rules must be entered in YAML-like format. The format is not really full compliant YAML, just YAML-like, and very strict in order to ensure the parser stays simple enough. Example of valid content:

# Test regexFilter: ^https:\/\/[a-z]{8}\.[a-z]{2,8}\/[!.+=@][\/0-9a-z]{20,30}\.[-a-z]{2,7}$
---
action:
  type: block
condition:
  urlFilter: ||delvenetworks.com/player/plugins/analytics/
---
action:
  type: block
condition:
  urlFilter: ||demandmedia.com/wm.js
---
action:
  type: block
condition:
  urlFilter: ||desipearl.com/tracker/
---

• The only accepted indentation is two spaces
• There must be no empty lines inside a DNR rule definition
• Each DNR rule must be separated with a --- line
• String values must not be quoted, otherwise the quotes will be considered part of the value
  • There is one exception: '' will be parsed as an empty string
• Lines starting with # are comments and will be ignored by the parser

Any line which does not match the parser's expectation will be marked as invalid. A DNR rule containing at least one invalid line will be ignored when the DNR rules are registered.

The custom DNR rules are registered when saving them to storage. The priority property is optional, uBOL will assign a priority just below that of the DNR rules used for "Trusted sites". If you supply a priority value, it will be added to the default value.

Though the parser will identify some errors, not all invalid DNR rules are currently identified by the parser at edit time. Invalid DNR rules not caught by the editor will cause errors when the DNR rules are registered. Registration errors will be reported in a panel at the top of the editor:

The editor will report regexFilter values which are not supported by the DNR engine on the current platform.

The editor reacts to instances of regexFilter: ... to report whether a regex value is supported on the current platform. This means you can test for a regex value by using # regexFilter: ... so that you do not have to create an actual DNR rules just for the sake of testing. When a regexFilter is found to be invalid, a tooltip for the value will show the error reported by the DNR API, which can be taken into account when trying to find a workaround.

The editor will attempt to auto-complete known DNR-related keywords.

Custom DNR rules can be exported into a JSON-based file, into a format known by the DNR API as a "static ruleset".

JSON-based rulesets can be imported, the content will be converted to valid YAML-like syntax expected by the parser.

When JSON content is pasted into the editor, it will attempt to convert to YAML. It's possible to paste partially or wholly JSON-based rulesets.

When disabling "Developer mode", all custom DNR rules will be unregistered from the browser's DNR engine. The custom DNR rules content will be left intact. Existing custom DNR rules will be registered into the DNR API when re-enabling "Developer mode".