How to add a new [PageFilter] 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 [Page Filters] that ship within JSPWiki, then you don't have to perform this step - they are already in your class path.

!!2. Tell JSPWiki you want to use this filter

Find the "filters.xml" file in your  {{webapps/''your wiki name''/WEB-INF}} -directory.  If you don't have one, create a new one as per the example below.

!Example configuration file

{{{
<?xml version="1.0"?>

<pagefilters>

   <filter>
      <class>com.ecyrd.jspwiki.filters.ProfanityFilter</class>
   </filter>
   
   <filter>
      <class>com.ecyrd.jspwiki.filters.PingWeblogsComFilter</class>

      <param>
         <name>url</name>
         <value>http://rpc.weblogs.com/RPC2</value>
      </param>

   </filter>

</pagefilters>
}}}

!Explanation on 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.

!!Using an alternate filters.xml

You can also set the location of the filters.xml -file from your {{jspwiki.properties}}-file.  For example, to set it to a config file in your /usr/local/jspwiki/config-dir, try:
{{{
jspwiki.filterConfig = /usr/local/jspwiki/config/filters.xml
}}}

----

Back to [PageFilters].

----
There's a bit of confustion about the proper location for {{filters.xml}}.
* The PageFilterConfiguration from the JSPWiki distribution states it should be in {{WEB-INF/lib}}
* The {{jspwiki.properties}} states (in the comment to {{jspwiki.filterConfig}} it should be in WEB-INF
* {{com.ecyrd.jspwiki.filters.~FilterManager}} looks it up in the classpath, which tells me it should be in {{WEB-INF/classes}}.
Now what's the correct location? --[Jawe]

----
I ended up configuring __jspwiki.filterConfig__ to specify an absolute path into the filters.xml.
{{{
jspwiki.filterConfig = /usr/local/jspwiki/etc/filters.xml
}}}
++[NiiloNeuvo]


----

There seems to be some confusion about the location of the __jar file__ versus the __filters.xml__ file. 

Jar files ''always'' go in {{WEB-INF/lib}}. 

The location for {{filters.xml}} used by the FilterManager is the one set by the value of {{jspwiki.filterConfig}} in jspwiki.properties. If this hasn't been set the default value (the value of {{DEFAULT_XMLFILE}} as defined in FilterManager) is {{/WEB-INF/filters.xml}}.

This being open source one can always look at the code for the final answer.  

-- MurrayAltheim


----

I just reviewed the code of FilterManager, and thought I would share my findings here. The process it follows to find the filters.xml file is:
# Looks for /WEB-INF/filters.xml. If not found goes no the next step.
# Looks in the classpath for a file named filters.xml. If not found goes no the next step.
# If a property named jspwiki.filterConfig has been set in the configuration file it interprets it as an absolute path in the file system and looks for the file there.
# If none of the methods above work it ignores the configuration and prints a trace of INFO level informing about it.

--JorgeFerrer, 22-Jan-2008