How to add a new WikiFilter to my JSPWiki?

Easy. Just follow the next few steps.

1. Add the JAR to your class path#

Typically, a PageFilter is shipped in a JAR -file. You have to put this JAR -file in your CLASSPATH somehow so that Java can find it. The easiest way is to just drop it to your webapps/your wiki name/WEB-INF/lib -directory.

If you are using any of the WikiFilters that ship with JSPWiki, then you don't have to perform this step - they are already in your classpath.

2. Tell JSPWiki you want to use this filter#

Find the "filters.xml" file in your WEB-INF -directory. If you don't have one, create a new one as per the example below.
The location of filters.xml can be customized with the jspwiki property:

jspwiki.filterConfig = /usr/local/tomcat/lib/filters.xml

Example configuration file#

<?xml version="1.0"?>
<pagefilters>
   <filter>
      <class>org.apache.wiki.filters.ProfanityFilter</class>
   </filter>
   <filter>
      <class>org.apache.wiki.filters.PingWeblogsComFilter</class>
      <param>
         <name>url</name>
         <value>http://rpc.weblogs.com/RPC2</value>
      </param>
   </filter>
</pagefilters>

Explanation of the different sections#

You can define as many filter -sections as you like. You can also define the same filter multiple times, in case you want to run the same filter many times. For example, you might want to ping multiple places using the PingWeblogsComFilter.

The order of the filters is significant: The filters are executed in exactly the same order as they appear in the "filters.xml" -file, so if you have many filters that modify the pages, you should be wary of the side effects =).

The parameters to the filters are defined inside the param -sections. A parameter has a "name" and a "value", both being free-form strings. A parameter may only occur once, i.e. the same name may occur only once in the whole filter -section.