Plugin Tutorial: How to create a function library

15/02/2008 12:46 by Sten Roger Sandvik

In this article I will describe how to create a function library plugin. This plugin type extends the data source functionality by providing user-defined functions. Each class can implement multiple functions and are attached an installation-unique plugin key.

Creating the plugin class

A function library does not need to extend a class or implement an interface. You can even use unmodified classes and export it as a function library.

A function can take any number of parameters, but restricts to simple types (int, string, boolean, int[], string[] and boolean[]). This restriction does not apply to return types, but if a return-type is not recognized it will call the toString() method.

Below shows our simple random-number plugin. This class has 3 methods that will be exported. The last one returns an xml-document. I use JDOM here, but you can also use W3C DOM as a return value for xml documents.

package mycompany;

import org.jdom.Document;
import org.jdom.Element;
import java.security.SecureRandom;
import java.util.Random;

public class RandomNumberPlugin
{
  private final Random random = new SecureRandom();
    
  public int getRandomNumber()
  {
    return this.random.nextInt();
  }

  public int[] getRandomNumbers(int count)
  {
    int[] result = new int[count];
    for (int i = 0; i < result.length; i++) {
      result[i] = getRandomNumber();
    }

    return result;
  }

  public Document getRandomNumbersDocument(int count)
  {
    int[] result = getRandomNumbers(count);
    Element root = new Element("numbers");
    for (int number : result) {
      root.addContent(new Element("number").setText(String.valueOf(number)));
    }

    return new Document(root);
  }
}

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 “radom-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 “radom-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="com.enonic.cms.api.plugin.FunctionLibraryPlugin">
    <property name="name" value="random"/>
    <property name="target">
      <bean class="mycompany.RandomNumberPlugin"/>
    </property>
  </bean>

</beans>

All function library plugins must have a installation-unique name. I use “random” in the above configuration.

Deploy the plugin

Now that you have “random-plugin.jar” and “random-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 use the user-defined functions you just deployed in either an object or a pagetemplate. If you now test with the following code:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <datasource>
    <methodname>random.getRandomNumbersDocument</methodname>
    <parameters>
      <parameter>10</parameter>
    </parameters>
  </datasource>
</datasources>

You should see the following when you execute the data source:

<?xml version="1.0" encoding="UTF-8"?>
<verticaldata>
  <context languagecode="en"/>
  <numbers>
    <number>-1995781838</number>
    <number>-395646641</number>
    <number>-62920182</number>
    <number>363611301</number>
    <number>656839586</number>
    <number>1334500105</number>
    <number>1291003612</number>
    <number>1231223780</number>
    <number>503486030</number>
    <number>-118373141</number>
  </numbers>
</verticaldata>

It is also possible to call the methods in script-controllers, but this is out of the scope for this tutorial. In later versions of Vertical Site we will build more around the function library plugin functionality.