How to write a JSPWiki Plugin.
See also


This documentation is using Windows, with Java (v1.7.0) already installed.

Install Eclipse#

Install Tomcat#

Install Maven#


Create new maven project#

First create a directory like:
  • /plugins/MyPlugin
In this directory create a single pom.xml file which is used by maven.
A plugin is simply a java jar file which interacts with JSPWiki classes.
In the below file change the groupId, artifactId and version as desired.
The scope of the jspwiki-war dependency is provided as this will be available in the application container (i.e. Tomcat).
<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="" xmlns:xsi="" xsi:schemaLocation="">

  <name>Maven Quick Start</name>

Create the following directory:
mkdir src\main\java
mkdir src\main\resources\ini
mkdir etc\myplugin\css
mkdir etc\myplugin\js
mkdir etc\myplugin\img
Once this is created run Maven:
mvn package
mvn eclipse:eclipse

Using Eclipse#

  • In Eclipse
  • Import - Existing Project Into Workspace - <MyPlugin dir> - MyPlugin - Finish
  • Create a new class
    • Package = com.jspwiki.plugin
    • Name = MyPlugin
  • Add:
    • import;
    • implements WikiPlugin
package com.jspwiki.plugin;

import java.util.Map;

import org.apache.log4j.Logger;

public class MyPlugin implements WikiPlugin {

        private final Logger log = Logger.getLogger(MyPlugin.class);

	public String execute(WikiContext wikiContext, Map<String, String> params) throws PluginException {"Plugin executed");
		/* Add CSS and Javascript resources */
		TemplateManager.addResourceRequest(wikiContext, TemplateManager.RESOURCE_SCRIPT, "myplugin/js/myplugin.js");
		TemplateManager.addResourceRequest(wikiContext, TemplateManager.RESOURCE_STYLESHEET, "myplugin/css/myplugin.css");
		/* Get the body of the plugin */
		String bodyHtml = "";
		String bodyWiki = params.get(DefaultPluginManager.PARAM_BODY);
		if (bodyWiki != null) {
			bodyHtml = wikiContext.getEngine().textToHTML(wikiContext,bodyWiki);
		/* Return the result */
		String result = "My Plugin rocks</br>"+bodyHtml;
		return result;

  • Create the /src/main/resources/ini/jspwiki_module.xml file
<?xml version="1.0" encoding="UTF-8"?>
   <plugin class="com.jspwiki.plugin.MyPlugin">
      <author>Your Name</author>
      <!-- Only the above two lines are required -->
  • Create the /src/main/resources/ configuration file:, stdout

# Direct log messages to stdout
log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %-5p %c{1}:%L - %m%n

Create the plugin#

  • Run mvn package
  • You will find /target/MyPlugin-1.0-SNAPSHOT.jar

Deploy the plugin#

I'm assuming you have Tomcat installed, and the 2.10.1 war file copied to /webroot/JSPWiki.war
  • Copy the above jar file to your tomcat <TomcatDir>/webroot/JSPWiki/WEB-INF/lib/
  • If you have custom CSS/JS, manually place the "/myplugin/" directory (with the css, js and img folders) into the <TomcatDir>/webroot/JSPWiki/ directory
    • When you use the plugin on a page it will add to the head element:
    <link rel='stylesheet' type='text/css' href='myplugin/css/myplugin.css' />
    <script type='text/javascript' src='myplugin/js/myplugin.js'></script>
    • Note: Currently I'm not sure how to reference these resources from within the jar file.
If you have the same plugin multiple times on a page, you will also get multiple CSS/JS includes.
I think this should be fixed in the TemplateManager somehow.
  • Or try the below with the bodyContent:

With __bold__ content


For the above example you can download the source code and plugin here: