Plugin Tutorial: How to create a controller

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

A controller is a code that does something to the response. It does not send the request down the chain. In this tutorial I will illustrate how to build a simple hello world controller. Yes, I said it was simple.

Create the plugin class

To create a controller plugin we need to extend the “HttpControllerPlugin” class. One method must be implemented: “handleRequest”. The controller acts the same way as a servlet.

package mycompany;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.enonic.cms.api.plugin.HttpControllerPlugin;
import java.io.PrintWriter;

public class HttpControllerExample
  extends HttpControllerPlugin
{
  public void handleRequest(HttpServletRequest req, HttpServletResponse res)
    throws Exception
  {
    PrintWriter out = res.getWriter();
    out.println("Hello World!");
    out.close();
  }
}

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 "controller-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 "controller-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.HttpControllerExample">
    <property name="urlPattern" value="/site/[0-3]/hello"/>
    <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 controllers and want a certain order.

Deploy the plugin

Now that you have "controller-plugin.jar” and "controller-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.