diff --git a/docs/general/ad-filtering/create-own-filters.md b/docs/general/ad-filtering/create-own-filters.md index 7d9acfeb250..8b4e54dc5d6 100644 --- a/docs/general/ad-filtering/create-own-filters.md +++ b/docs/general/ad-filtering/create-own-filters.md @@ -3871,12 +3871,24 @@ Filter URL: `https://example.org/path/filter.txt` #### Conditions {#conditions-directive} -Filters maintainers can use conditions to supply different rules depending on the ad blocker type. When an adblocker encounters an `!#if` directive, followed eventually by an `!#endif` directive, it will compile the code inside of the directives block only if the specified condition is true. Condition supports all the basic logical operators. +Filters maintainers can use conditions to supply different rules depending on the ad blocker type. +A conditional directive beginning with a `!#if` directive must explicitly be terminated with an `!#endif` directive. +Conditions support all basic logical operators. -A conditional directive beginning with an `!#if` directive must explicitly be terminated with an `!#endif` directive. +There are two possible scenarios: + +1. When an ad blocker encounters an `!#if` directive and no `!#else` directive, + it will compile the code between `!#if` and `!#endif` directives only if the specified condition is true. + +1. If there is an `!#else` directive, the code between `!#if` and `!#else` will be compiled if the condition is true; + otherwise, the code between `!#else` and `!#endif` will be compiled. + +:::note Whitespaces matter. `!#if` is a valid directive, while `!# if` is not. +::: + **Syntax** ```adblock @@ -3885,10 +3897,23 @@ rules_list !#endif ``` +or + +```adblock +!#if (conditions) +true_conditions_rules_list +!#else +false_conditions_rules_list +!#endif +``` + where: -- `!#if (conditions)` — start of the block -- `conditions` — just like in some popular programming languages, preprocessor conditions are based on constants declared by ad blockers. Ad blocker authors define on their own what exact constants do they declare. Possible values: +- `!#if (conditions)` — start of the block when conditions are true +- `conditions` — just like in some popular programming languages, + preprocessor conditions are based on constants declared by ad blockers. + Authors of ad blockers define on their own what exact constants they declare. + Possible values: - `adguard` always declared; shows maintainers that this is one of AdGuard products; should be enough in 95% of cases - product-specific constants for cases when you need a rule to work (or not work — then `!` should be used before constant) in a specific product only: - `adguard_app_windows` — AdGuard for Windows @@ -3901,8 +3926,9 @@ where: - `adguard_ext_edge` — AdGuard Browser Extension for Edge Legacy - `adguard_ext_opera` — AdGuard Browser Extension for Opera - `adguard_ext_android_cb` — AdGuard Content Blocker for mobile Samsung and Yandex browsers - - `ext_ublock` — special case; this one is declared when a uBlock version of a filter is compiled by the [FiltersRegistry](https://github.com/AdguardTeam/FiltersRegistry) -- `rules_list` — list of rules + - `ext_ublock` — special case; this one is declared when a uBlock version of a filter is compiled by the [FiltersRegistry] +- `!#else` — start of the block when conditions are false +- `rules_list`, `true_conditions_rules_list`, `false_conditions_rules_list` — lists of rules - `!#endif` — end of the block **Examples** @@ -3922,6 +3948,31 @@ domain.com##div.ad !#endif ``` +```adblock +!#if (adguard && !adguard_ext_safari) +! for all AdGuard products except AdGuard for Safari +||example.org^$third-party +domain.com##div.ad +!#else +! for AdGuard for Safari only +||subdomain.example.org^$third-party +!#endif +``` + +:::info Compatibility + +The `!#else` directive is supported by the [FiltersDownloader][gh-filters-downloader] v1.1.20 or later. + +It is already supported for filter lists compiled by the [FiltersRegistry], +but it still may not be supported by AdGuard products when adding a filter list with `!#else` as a custom one. +The following products will support it in the mentioned versions or later: + +- AdGuard for Windows, Mac, and Android, running CoreLibs v1.13; +- AdGuard Browser Extension v4.2.208; +- AdGuard for Safari v1.11.16. + +::: + #### Safari affinity {#safari-affinity-directive} Safari's limit for each content blocker is 150,000 active rules. But in AdGuard for Safari and AdGuard for iOS, we've split the rules into 6 content blockers, thus increasing the rule limit to 900,000. @@ -3983,7 +4034,7 @@ example.org#@#.adBanner ### Hints -"Hint" is a special comment, instruction to the filters compiler used on the server side (see [FiltersRegistry](https://github.com/AdguardTeam/FiltersRegistry)). +"Hint" is a special comment, instruction to the filters compiler used on the server side (see [FiltersRegistry]). **Syntax** @@ -4222,3 +4273,5 @@ The following scriptlets also may be used for debug purposes: [and-cb]: #what-product "AdGuard Content Blocker for Samsung Internet and Yandex Browser on Android" [sec-fetch-dest-header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Dest +[gh-filters-downloader]: https://github.com/AdguardTeam/FiltersDownloader +[FiltersRegistry]: https://github.com/AdguardTeam/FiltersRegistry