Plugin Tutorial: How to create a markup filter

15/02/2008 13:08 by Sten Roger Sandvik

A response filter is a code that filters any textural output from a redered page. The filter can do anything with the text, like replace some tokens. In this example I will illustrate the replacement of a token with some data. Binary responses will not be filtered by this plugin.

Create the plugin class

To create a controler plugin we need to extend the “HttpResponseFilterPlugin” class. One method must be implemented: “filterResponse”. This method takes the source request, text response that was generated by Vertical Site and the content type of the response. Response is returned by the function as text.

package mycompany;

import javax.servlet.http.HttpServletRequest;
import com.enonic.cms.api.plugin.HttpResponseFilterPlugin;

public class HttpResponseFilterExample
  extends HttpResponseFilterPlugin
{
  private final static String TAG_TO_REPLACE = "##ip##";
    
  public String filterResponse(HttpServletRequest req, String textResponse, 
                               String contentType)
    throws Exception
  {
    String remoteAddr = request.getRemoteAddr();
    return textResponse.replaceAll(TAG_TO_REPLACE, remoteAddr);
  }
}

In the above example we replace ##ip## with the actual ip of the client and returns the filtered text.

All the code created should be packaged into a jar file. This jar file has no name restrictions, but in my example I will call it "filter-plugin.jar”.

Creating the configuration

Before you can deploy this plugin to the server, you have to create a deployment configuration for this plugin. The descriptor uses spring configuration and you can incject the plugin with all sorts of external beans.

The configuration file name must end with “-plugin.xml” to be recognized by the plugin loader. In this example I will call it "filter-plugin.xml”.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
         http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

  <bean class="mycompany.HttpResponseFilterExample">
    <property name="urlPattern" value="/site/[0-3]/.*"/>
    <property name=”priority” value=”0”/>
  </bean>

</beans>

All http based plugins has two settings: “urlPattern” and “priority”. The “urlPattern” is a regular expression that is used to match which requests that should be intercepted. The “priority” is used if you have multiple filters and want a certain order.

Deploy the plugin

Now that you have "filter-plugin.jar” and "filter-plugin.xml” we can deploy it to the server. All files must be placed under $CMS_HOME/plugins directory. You can place any sub-directory into this directory, so all files under any sub-directory will be searched.

I place the files right into the root of $CMS_HOME/plugins directory. Restart the application and the plugins will be available. You can go to the front page of Vertical Site to check what kind of plugins where loaded.

If you need any additional jar files available, you just put it into the plugins directory to be loaded in Vertical Site.

Using the plugin

You can now test the plugin by entering one of the urls that matches the pattern you defined in the configuration. If you have a page with the ##ip## text anywhere it will replace it by the ip (like 127.0.0.0).