diff --git a/doc/guide/en/Content_Filters.mc b/doc/guide/en/Content_Filters.mc new file mode 100644 index 000000000..8c387e1c1 --- /dev/null +++ b/doc/guide/en/Content_Filters.mc @@ -0,0 +1,98 @@ +Content Filters +=============== + + +### Overview + +The **Content Filter** app (when installed) allows you to filter incoming content from all sources or from specific connections. The filtering may be based on words, tags, regular expressions, or language. + +You can set global filters for all incoming content in the Content Filter app. + +You can also set individual filters for each of your Connections. Select "Edit" for any connection, then look under Custom Filter. + +If you add filters under **Do not import posts with this text**, these are applied first. Any matching content will be removed. + +Then, any filters under **Only import posts with this text** are applied. Only matching content will be kept, and everything that doesn't match will be removed. + + +### Basic Filters + +**TEXT** + +**Any text that doesn't start with one of the following: lang= lang!= # $ ? /** +Case-insensitive text match +Example: `covid` (matches "covid", "COVID", "Covid", etc) + + +**LANGUAGE** + +**lang=** +Match language if it can be identified +Example: `lang=de` (matches German-language content) + +**lang!=** +Anything except this language +Example: `lang!=en` (matches non-English content) + + +**HASHTAG** + +**#[zrl=https://forum.statler.ws/search?tag=%2A%2A]**[/zrl] +Match hashtag +Example: `#[zrl=https://forum.statler.ws/search?tag=cats%60]cats`[/zrl] + + +**CATEGORY** + +**$** +Match category (requires installing the **Categories** app). Categories are "personal hashtags" that do not generally federate with other instances. +Example: `$Science` + + +**ITEMS AND FIELDS** + +**?** +Discussed below under **Advanced Filters** + + +**REGULAR EXPRESSIONS (REGEX)** + +**/** +Match a "regular expression". See numerous online help sites such as [Regular-Expressions.info](https://www.regular-expressions.info/) for regex assistance. +Example: `/gr[ae]y/` (matches "gray" and "grey") + + +### Advanced Filters + +**ITEMS** + +**?** +You can do a string/numeric/array/boolean match on the database fields of an item (a post, comment, etc). A complete listing is beyond the scope of this document, but see `install/schema_mysql.sql` and search for `CREATE TABLE IF NOT EXISTS [nomd]`[/nomd]item[nomd]`[/nomd]`. Here is a sampling: +* `body` (text of the message) +* `verb` (what this item does) +* `item_thread_top` (first post in a thread, boolean) +* `item_private` (0 = public message, 1 = restricted message, 2 = direct message) +* ...etc... + +Available comparison operators are: +* `?foo ~= baz` -- item.foo contains the string 'baz' +* `?foo == baz` -- item.foo is the string 'baz' +* `?foo != baz` -- item.foo is not the string 'baz' +* `?foo >= 3` -- item.foo is greater than or equal to 3 +* `?foo > 3` -- item.foo is greater than 3 +* `?foo <= 3` -- item.foo is less than or equal to 3 +* `?foo < 3` -- item.foo is less than 3 +* `?foo {} baz` -- 'baz' is an array element in item.foo +* `?foo {\*} baz` -- 'baz' is an array key in item.foo +* `?foo` -- true condition for item.foo +* `?!foo` -- false condition for item.foo (The values 0, '', an empty array, and an unset value will all evaluate to false) + +Example: `?verb == Announce` (matches ActivityPub "boosts") + + +**FIELDS** + +**?+** +Field match: ?+field item.object +*Usage is undocumented at present*[/share] +@[zrl=https://forum.statler.ws/channel/billstatler]Bill Statler[/zrl]