Just filling in a CamelGap...

Writing Plugins - A Step By Step Introduction#

by TomZ

Please add comments at the end [1] of this document.

To be fair: RozekPlugins also provides good docu. Decide what you like...


Caution: The code provided does not follow the coding standards Janne suggested in MyCodingStandards. While I am thinking every coder should following his own style I would like to suggest to follow Janne's rules when planning to code a plugin that you would like to see the in the core of JspWiki.

Our Goal#

We are going to write a JSPWiki plugin that can be used like this (Mind the single quotes! Double quotes will not work):
[{HelloYouPlugin name='tomZ'}]

It should render to (mind that the text is in italic):

Hello, tomZ

[{HelloYouPlugin}]
(mind the missing name attribute!) should render to:

Hello, Missing Name

What You Need#

  • A working Ant
  • A JSPWiki source distribution (I used 2.0.39 for when I wrote this text)
  • A working JSPWiki (2.0.39 or later) running on a Tomcat

Those requirements are just there to assure that procedures defined within this document can be applied without any changes to your system. If you know what you do the ideas should be applicable to any system running JSPWiki.

Moreover, while I am using the build mechanism that comes with JSPWiki, I will not tell you how to install JSPWiki (see InstallingJSPWiki). It's just a trick to

save you from a lot of compile time setup hazards.

Setup#

Create a directory named jspwiki-plugin in your home directory by typing mkdir ~/jspwiki-plugin. cd to this directory and copy the JSPWiki tarball to this directory.

Uncompress your JSPWiki distribution and cd to the JSPWiki directory. If servlet.jar is not in your classpath just copy it to the lib/ directory.

Now call ant from the command line. JSPWiki should compile w/o complaints.

Preparations#

We will use a package called tomz for our plugin. Therefore create a new directory named tomz in src/ (mkdir src/tomz).

Coding the Plugin#

Ok, now we can start coding our plugin.Fire up vim (or whatever editor you like) by typing vim src/tomz/HelloYouPlugin.java.

Declare The Package#

We will put our class in the package tomz. Hence, type:
package tomz;

Inherit The Interface#

Our class has to implement the interface WikiPlugin. Therefore we add the following code (mind the import!):
package tomz;

import com.ecyrd.jspwiki.plugin.WikiPlugin;

public class HelloYouPlugin implements WikiPlugin {
}

Implement The Interface Methods#

WikiPlugin declares just one methode: public String execute (WikiContext Context, Map ParameterMap). Lets implement this methode. To satisfy the compiler we will need to import WikiContext and java.util.Map.
package tomz;

import com.ecyrd.jspwiki.plugin.WikiPlugin;
import com.ecyrd.jspwiki.WikiContext;
import java.util.Map;

public class HelloYouPlugin implements WikiPlugin {
  public String execute (WikiContext Context, Map ParameterMap) {
    return "<i>Hello, <b>Missing Name!</b></i>";
  }
}

This code should compile. Try it by calling ant from the command line. When we leave out installation issues (which I will discuss later on), we have a working JSPWiki plugin.The plugin does not do any useful thing, but it is a correct and working JSPWiki plugin.

Display The Name#

All parameters that are defined when the plugin's execute methode is called are passed in thru the ParameterMap map. You will find our name to display by querying the key name. Caution! Your code must be prepared for the case that the key you are looking for is not there.
package tomz;

import com.ecyrd.jspwiki.plugin.WikiPlugin;
import com.ecyrd.jspwiki.WikiContext;
import java.util.Map;

public class HelloYouPlugin implements WikiPlugin {
  public String execute (WikiContext Context, Map ParameterMap) {
     String name=null;
     if(ParameterMap != null) { // just because I am somehow paranoid
         name = (String)ParameterMap.get("name");
     }
     // unless name provided use "Missing Name"
     name = (name != null ? name : "Missing Name");
     return "<i>Hello, <b>"+name+"</b></i>";
  }
}

This code will do the same as the last one, in the case, that the name attribute is omitted. If this attribute is given it will show the content of this attribute.

Time To Install#

After our last ant run you should have got a HelloYouPlugin.class in build/tomz. Now we need to make it available for JSPWiki. Again, I assume you got an installed version of JSPWiki in $TOMCAT_HOME/webapps/JSPWiki!

Make JSPWiki Find Our Plugin#

JSPWiki has a defined way how it will find plugins. We will go along this path right now.

First, cd to $TOMCAT_HOME/webapps/JSPWiki/WEB-INF. Chances are, that you need to be root to go there and/or edit files in there.

Fire up vim via vim jspwiki.properties. Search for jspwiki.plugin.searchPath. Add tomz. If there are already entries, do it like that: jspwiki.plugin.searchPath = entryA, entryB, tomz (How it works is documented in the source).

Having done so, we have told JSPWiki to look for plugins in the package named tomz. That means, since JSPWiki is a web application, the classloader will analyze all entries in WEB-INF/classes and WEB-INF/lib, and find our new plugin.

Make Tomcat Find Our Plugin#

Eventually, we need to physically make our plugin available to JSPWiki.

First, cd to $TOMCAT_HOME/webapps/JSPWiki/WEB-INF/classes. Now, do a mkdir tomz and move to this directory by cd tomz.

Copy our new plugin class to this location:

cp ~/jspwiki-plugin/JSPWiki/build/tomz/HelloYouPlugin.class .
(Dont miss this little dot at the end. As small as it is as important --- like we all know: size doesn't matter ;-)

Restart Tomcat#

Now restart your Tomcat. Your plugin should be ready for use. If it works: Congratz!

Comments [#1]#

A nice and simple plugin. Instead of the last step though, Make Tomcat Find Our Plugin you can ,after calling ant compile / ant jar, just copy (overwrite) JSPWiki/build/JSPWiki.jar into $TOMCAT_HOME/webapps/JSPWiki/WEB-INF/lib, restart tomcat and it works!

Erik Alm, 6 Aug 2005: Here's how you can use InitializablePlugin to get your plugin initialized by the wiki (works for version 2.2.27 and later).


Hi and thanks for posting a page like this , particularily for people like me who are java deprived - skill...

Trying it out I get (followed the above steps and below at the point of calling ant):


Ant version 1.4.1 compiled on September 3 2002
Searching for build.xml ...
Buildfile: /home/bhayward/jspwiki-plugin/JSPWiki/build.xml
Detected Java version: 1.4 in: /usr/j2se/jre
Detected OS: SunOS
parsing buildfile /home/bhayward/jspwiki-plugin/JSPWiki/build.xml with URI = file:/home/bhayward/jspwiki-plugin/JSPWiki/build.xml
Project base dir set to: /home/bhayward/jspwiki-plugin/JSPWiki
property Override ignored for build.properties
property Loading /home/bhayward/jspwiki-plugin/JSPWiki/build.properties
property Loading Environment env.

BUILD FAILED

/home/bhayward/jspwiki-plugin/JSPWiki/build.xml:247: The <javadoc2> task doesn't support the nested "packageset" element.


Searching google doesn't help me much. Can anyone point out the obvious? Thanks

--Bruce E Hayward, 16-May-2006

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-42) was last changed on 28-Apr-2010 15:38 by MagnusL