From 2cc3fbf31c51506a6fdf88c86871c399f5bd1141 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Mon, 7 Aug 2023 16:34:53 +0300 Subject: [PATCH 1/7] Modify the HTML rules description --- .../ad-filtering/create-own-filters.md | 63 +++++++++++++++---- 1 file changed, 50 insertions(+), 13 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index af596908c1f..7bad586c964 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3032,19 +3032,25 @@ HTML filtering rules are supported by AdGuard for Windows, Mac, Android, and AdG ::: -**Syntax** +### Syntax ``` - rule = [domains] "$$" tagName [attributes] - domains = [domain0, domain1[, ...[, domainN]]] -attributes = "[" name0 = value0 "]" "[" name1 = value2 "]" ... "[" nameN = valueN "]" + selector = [tagName] [attributes] [pseudoClasses] + combinator = ">" + rule = [domains] "$$" selector *(combinator selector) + domains = [domain0, domain1[, ...[, domainN]]] + attributes = "[" name0 = value0 "]" "[" name1 = value2 "]" ... "[" nameN = valueN "]" +pseudoClasses = pseudoClass *pseudoClass + pseudoClass = ":" pseudoName [ "(" pseudoArgs ")" ] ``` * **`tagName`** — name of the element in lower case, for example, `div` or `script`. * **`domains`** — domain restriction for the rule. Same principles as in [element hiding rules syntax](#elemhide-syntax). * **`attributes`** — a list of attributes, that limit the elements selection. `name` — attribute name, `value` — substring, that is contained in attribute value. +* **`pseudoName`**` — the name of a pseudo-class. +* **`pseudoArgs`**` — the arguments of a function-style pseudo-class. -**Examples** +### Examples **HTML code:** ```html @@ -3058,11 +3064,17 @@ example.org$$script[data-src="banner"] This rule removes all `script` elements with the attribute `data-src` containing the substring `banner`. The rule applies only to `example.org` and all its subdomains. -**Special attributes** +### Special attributes In addition to usual attributes, which value is every element checked for, there is a set of special attributes that change the way a rule works. Below there is a list of these attributes: -* **`tag-content`** +#### `tag-content` + +:::caution Deprecation notice + +The use of this special tag is deprecated in favor of the `:contains()` pseudo-class. + +::: This is the most frequently used special attribute. It limits selection with those elements whose innerHTML code contains the specified substring. @@ -3081,11 +3093,13 @@ Following rule will delete all `script` elements with a `banner` substring in th $$script[tag-content="banner"] ``` -**Nested elements** +#### `wildcard` + +:::caution Deprecation notice -If we are dealing with multiple nested elements and they all fall within the same HTML filtering rule, they all are going to be deleted. +The use of this special tag is deprecated in favor of the `:contains()` pseudo-class. -* **`wildcard`** +::: This special attribute works almost like `tag-content` and allows you to check the innerHTML code of the document. Rule will check if HTML code of the element fits to the [search pattern](https://en.wikipedia.org/wiki/Glob_(programming)). @@ -3097,7 +3111,7 @@ For example: It will check, if the code of element contains two consecutive substrings `banner` and `text`. -* **`max-length`** +#### `max-length` Specifies the maximum length for content of HTML element. If this parameter is set and the content length exceeds the value, a rule does not apply to the element. @@ -3111,7 +3125,7 @@ $$div[tag-content="banner"][max-length="400"] ``` This rule will remove all the `div` elements, whose code contains the substring `banner` and the length of which does not exceed `400` characters. -* **`min-length`** +#### `min-length` Specifies the minimum length for content of HTML element. If this parameter is set and the content length is less than preset value, a rule does not apply to the element. @@ -3122,7 +3136,30 @@ $$div[tag-content="banner"][min-length="400"] This rule will remove all the `div` elements, whose code contains the substring `banner` and the length of which exceeds `400` characters. -**Exceptions** +### Pseudo-classes + +#### `:contains()` + +##### Syntax +``` +:contains(unquoted text) +``` +or +``` +:contains(/reg(ular )?ex(pression)?/) +``` + +:::note Compatibility + +`:-abp-contains()` and `:has-text()` are synonyms for `:contains()`. + +::: + +Requires that the element's inner HTML contains the specified text or matches the specified regular expression. + +As with the `tag-content` and `wildcard` attributes, specifying a `:contains()` pseudo-class on a non-leaf selector is not supported. + +### Exceptions Similar to hiding rules, there is a special type of rules that disable the selected HTML filtering rule for particular domains. The syntax is the same, you just have to change `$$` to `$@$`. From 167adc6bb9a92dad7971d3557c35b5c4452d9d6b Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Mon, 7 Aug 2023 16:39:10 +0300 Subject: [PATCH 2/7] Fix typo --- docs/general/ad-filtering/create-own-filters.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 7bad586c964..767264fac77 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3072,7 +3072,7 @@ In addition to usual attributes, which value is every element checked for, there :::caution Deprecation notice -The use of this special tag is deprecated in favor of the `:contains()` pseudo-class. +The use of this special attribute is deprecated in favor of the `:contains()` pseudo-class. ::: @@ -3097,7 +3097,7 @@ $$script[tag-content="banner"] :::caution Deprecation notice -The use of this special tag is deprecated in favor of the `:contains()` pseudo-class. +The use of this special attribute is deprecated in favor of the `:contains()` pseudo-class. ::: From d40536559fb3260563d44f90cede3c126e85c072 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Mon, 7 Aug 2023 16:41:00 +0300 Subject: [PATCH 3/7] Add compatibility note --- docs/general/ad-filtering/create-own-filters.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 767264fac77..a63c4283ca5 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3155,6 +3155,12 @@ or ::: +:::info Compatibility + +The `:contains()` pseudo-class is supported by AdGuard for Windows, Mac, and Android, **running CoreLibs version 1.13 or later**. + +::: + Requires that the element's inner HTML contains the specified text or matches the specified regular expression. As with the `tag-content` and `wildcard` attributes, specifying a `:contains()` pseudo-class on a non-leaf selector is not supported. From 1c68acdc5f2deb53a4f9f9bd44db8359b70f1a00 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Tue, 8 Aug 2023 17:56:22 +0300 Subject: [PATCH 4/7] Slightly reword the deprecation warnings --- docs/general/ad-filtering/create-own-filters.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index a63c4283ca5..57e22f8cd98 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3072,7 +3072,7 @@ In addition to usual attributes, which value is every element checked for, there :::caution Deprecation notice -The use of this special attribute is deprecated in favor of the `:contains()` pseudo-class. +This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class where it is available. ::: @@ -3097,7 +3097,7 @@ $$script[tag-content="banner"] :::caution Deprecation notice -The use of this special attribute is deprecated in favor of the `:contains()` pseudo-class. +This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class where it is available. ::: From e63dcf2975aaf688f07bfe4713c0c37c38e89a23 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Fri, 11 Aug 2023 15:23:13 +0300 Subject: [PATCH 5/7] Some edits --- .../ad-filtering/create-own-filters.md | 49 +++++++++++++++++-- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 57e22f8cd98..4da455b68aa 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3047,8 +3047,9 @@ pseudoClasses = pseudoClass *pseudoClass * **`tagName`** — name of the element in lower case, for example, `div` or `script`. * **`domains`** — domain restriction for the rule. Same principles as in [element hiding rules syntax](#elemhide-syntax). * **`attributes`** — a list of attributes, that limit the elements selection. `name` — attribute name, `value` — substring, that is contained in attribute value. -* **`pseudoName`**` — the name of a pseudo-class. -* **`pseudoArgs`**` — the arguments of a function-style pseudo-class. +* **`pseudoName`** — the name of a pseudo-class. +* **`pseudoArgs`** — the arguments of a function-style pseudo-class. +* **`combinator`** — an operator that works similarly to the [CSS child combinator](insert link to MDN): that is, the `selector` on the right of the `combinator` will only match an element whose direct parent matches the `selector` on the left of the `combinator`. ### Examples @@ -3093,6 +3094,12 @@ Following rule will delete all `script` elements with a `banner` substring in th $$script[tag-content="banner"] ``` +:::caution Limitations + +The `tag-content` special attribute may not appear in a selector to the left of a `>` combinator. + +::: + #### `wildcard` :::caution Deprecation notice @@ -3111,8 +3118,20 @@ For example: It will check, if the code of element contains two consecutive substrings `banner` and `text`. +:::caution Limitations + +The `wildcard` special attribute may not appear in a selector to the left of a `>` combinator. + +::: + #### `max-length` +:::caution Deprecation notice + +This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class with a regular expression where it is available. + +::: + Specifies the maximum length for content of HTML element. If this parameter is set and the content length exceeds the value, a rule does not apply to the element. **Default value** @@ -3125,8 +3144,20 @@ $$div[tag-content="banner"][max-length="400"] ``` This rule will remove all the `div` elements, whose code contains the substring `banner` and the length of which does not exceed `400` characters. +:::caution Limitations + +The `max-length` special attribute may not appear in a selector to the left of a `>` combinator. + +::: + #### `min-length` +:::caution Deprecation notice + +This special attribute may become unsupported in the future. Prefer using the `:contains()` pseudo-class with a regular expression where it is available. + +::: + Specifies the minimum length for content of HTML element. If this parameter is set and the content length is less than preset value, a rule does not apply to the element. For example: @@ -3136,6 +3167,12 @@ $$div[tag-content="banner"][min-length="400"] This rule will remove all the `div` elements, whose code contains the substring `banner` and the length of which exceeds `400` characters. +:::caution Limitations + +The `min-length` special attribute may not appear in a selector to the left of a `>` combinator. + +::: + ### Pseudo-classes #### `:contains()` @@ -3161,9 +3198,13 @@ The `:contains()` pseudo-class is supported by AdGuard for Windows, Mac, and And ::: -Requires that the element's inner HTML contains the specified text or matches the specified regular expression. +Requires that the inner HTML of the element contains the specified text or matches the specified regular expression. -As with the `tag-content` and `wildcard` attributes, specifying a `:contains()` pseudo-class on a non-leaf selector is not supported. +:::caution Limitations + +A `:contains()` pseudo-class may not appear in a selector to the left of a `>` combinator. + +::: ### Exceptions From 76479d9bfefbed9102cbc58d11ff626c4f671f70 Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Fri, 11 Aug 2023 16:09:09 +0300 Subject: [PATCH 6/7] Fix --- docs/general/ad-filtering/create-own-filters.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 4da455b68aa..47c42f2733a 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3096,7 +3096,7 @@ $$script[tag-content="banner"] :::caution Limitations -The `tag-content` special attribute may not appear in a selector to the left of a `>` combinator. +The `tag-content` special attribute must not appear in a selector to the left of a `>` combinator. ::: @@ -3120,7 +3120,7 @@ It will check, if the code of element contains two consecutive substrings `banne :::caution Limitations -The `wildcard` special attribute may not appear in a selector to the left of a `>` combinator. +The `wildcard` special attribute must not appear in a selector to the left of a `>` combinator. ::: @@ -3146,7 +3146,7 @@ This rule will remove all the `div` elements, whose code contains the substring :::caution Limitations -The `max-length` special attribute may not appear in a selector to the left of a `>` combinator. +The `max-length` special attribute must not appear in a selector to the left of a `>` combinator. ::: @@ -3169,7 +3169,7 @@ This rule will remove all the `div` elements, whose code contains the substring :::caution Limitations -The `min-length` special attribute may not appear in a selector to the left of a `>` combinator. +The `min-length` special attribute must not appear in a selector to the left of a `>` combinator. ::: @@ -3202,7 +3202,7 @@ Requires that the inner HTML of the element contains the specified text or match :::caution Limitations -A `:contains()` pseudo-class may not appear in a selector to the left of a `>` combinator. +A `:contains()` pseudo-class must not appear in a selector to the left of a `>` combinator. ::: From 49ee7dbb9a18098e1dc48592a9480ec20097d71b Mon Sep 17 00:00:00 2001 From: Nikita Gorskikh Date: Mon, 28 Aug 2023 11:47:04 +0300 Subject: [PATCH 7/7] Fix link --- docs/general/ad-filtering/create-own-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 4e1ffd9d4cd..28fee417b0a 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3283,7 +3283,7 @@ pseudoClasses = pseudoClass *pseudoClass * **`attributes`** — a list of attributes, that limit the elements selection. `name` — attribute name, `value` — substring, that is contained in attribute value. * **`pseudoName`** — the name of a pseudo-class. * **`pseudoArgs`** — the arguments of a function-style pseudo-class. -* **`combinator`** — an operator that works similarly to the [CSS child combinator](insert link to MDN): that is, the `selector` on the right of the `combinator` will only match an element whose direct parent matches the `selector` on the left of the `combinator`. +* **`combinator`** — an operator that works similarly to the [CSS child combinator](https://developer.mozilla.org/en-US/docs/Web/CSS/Child_combinator): that is, the `selector` on the right of the `combinator` will only match an element whose direct parent matches the `selector` on the left of the `combinator`. ### Examples