WordPress.org

Technically, all you need to do is copy the "text-filter-suite" folder into your "wp-content/plugins" directory, then activate the "TFS Core" plugin from the WordPress admin interface. But, more generally, you'll probably want some of the other filter files, as well. The easiest thing to do will be to just copy all of the ".php" files to your plugins directory, and only activate the ones that interest you. But you can omit any of the "tfs-whatever.php" files (other than tfs-core) that don't interest you.

Using the filters

Generally, you'll probably want to activate a filter just for specific posts. You do this by adding special "post custom fields" in the "Write Post" form.

Custom fields are composed of two parts: the "key" and the "value". The two special keys that activate TFS are "postfilter" and "commentfilter". In either case, the value should be the short name of the TFS filter you wish to apply, e.g. "pirate" or "fudd" (without the quotation marks).

Setting the "postfilter" key will apply the filter to the main post text. Setting the "commentfilter" key will apply the filter to the text of all comments on the post.

Technical mumbo-jumbo

There are only two core TFS functions, plus two more to support the per-post content and comment filtering based on post custom fields. The main entry point is the "filtercdatacontent" function. A TFS filter will call filtercdatacontent, passing the content and the name of a second function. The magic of filtercdatacontent() is that it will only mangle regular text, leaving HTML tags alone. It will automatically call out to the named function, passing it each chunk of non-HTML-tag text (AKA "CDATA", or "Character Data", in XML parlance) in turn.

The other core function is "arrayapplyregexp". This support function isn't required for every filter, but it is at the core of the included TFS filters, such as the "pirate" filter. It accepts an associative array of regular expressions and replacements, and the content to be filtered. Examine the source of the "chef" and "fudd" filters for some simple examples.

The per-post support functions are "tfscontentfilter" and "tfscommentfilter". These functions are automatically applied to each post and its contents. They look for the "contentfilter" and "commentfilter" post custom fields, and apply the appropriate filter functions if they are found.

Lastly, the core functions will look for a querystring variable named "filter", and attempt to apply the named filter to the current page view. For example, if you browse to "http://example.com/?filter=fudd", all content will have the "fudd" filter applied to it, regardless of whether any TFS-related post custom fields are set.