See also:

See the starting point for developing custom plugins to create a maven project holding the custom plugin.


Basic plugins#

  • Create a new class
    • Package = com.jspwiki.extensions.plugin
    • Name = MyPlugin
  • Add:
    • import;
    • implements Plugin
package com.jspwiki.extensions.plugin;

import java.util.Map;

import org.apache.log4j.Logger;

public class MyPlugin implements Plugin {

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

	public String execute( Context 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( PluginManager.PARAM_BODY );
		if( bodyWiki != null ) {
			bodyHtml = wikiContext.getEngine().textToHTML( wikiContext, bodyWiki );
		/* Return the result */
		return "My Plugin rocks</br>" + bodyHtml;

About XSS Vulnerabilities It is up to the plugin (and the plugin author) to be cautious about the rendered html. Especially if the plugin is composing the html by means of string handling. For example, the TableOfContents plugin has a title parameter which get's rendered as an h4 in the plugin's output. The plugin will call TextUtil.replaceEntities(title) before inserting it into the html stream, so malicious <script>'s cannot survive. If the plugin would be using eg jdom2 to render the output html, chances are that there is less to worry about.
Bundling static resources in your plugin Thanks to Servlet's 3.1 specification, static resources can be placed inside the ./META-INF/resources folder of your plugin (f.ex., inside ./META-INF/resources/myplugin/css, ./META-INF/resources/myplugin/js, etc.) and they will be automatically available on the JSPWiki instance as $JSPWIKI_CONTEXT_URL/myplugin/whatever_here.

Plugin parameters and body#

All the parameters defined on plugin invocation are passed as a Map of key-value pairs on the execute(..) method. Also, this Map contains three special parameters, denoted by constants on the

  • PluginManager.PARAM_BODY: contains the plugin's body, as seen on the above example.
  • PluginManager.PARAM_CMDLINE: contains the command line content parameter (i.e, the verbatim plugin's invocation).
  • PluginManager.PARAM_BOUNDS: contains the start and end positions in the read stream of the plugin text (stored as a two-element int, start and end resp.).
  • PluginManager.PARAM_DEBUG: special parameter debug that, when passed to the plugin, outputs debug information.
note These special parameters are guaranteed to work when using JSPWiki's default markup parser (yes, it is possible to plug in other markup parsers... but that's another story). Other markup parsers may or may not respect any or all of these special parameters.


If the custom plugin needs to perform some kind of initialization involving the Engine, then it can also implement the interface.

The plugin will then be called exactly once prior to the actual execute(..) routine. If the plugin has its own declaration in jspwiki_modules.xml, then it is called during startup - otherwise it is called the first time the plugin is encountered.


If a plugin implements the interface, then JSPWiki will call the executeParse(..) method from this interface when JSPWiki is forming the DOM tree. An incomplete DOM tree, as well as the regular parameters will be received. However, since JSPWiki caches the DOM tree to speed up later places, which means that whatever this method returns would be irrelevant. Some DOM tree manipulation can be done, here though.

Unit testing#

See JSPWikiPublicAPI#Testing

Optional tasks#

  • Declare plugin resources: 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 -->
  • Add the following properties to your jspwiki-[custom].properties configuration file:, stdout

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



<link rel='stylesheet' type='text/css' href='myplugin/css/myplugin.css' />
<script type='text/javascript' src='myplugin/js/myplugin.js'></script>
If you have the same plugin multiple times on a page, you will also get multiple CSS/JS includes.
  • Restart your tomcat
    • http://localhost:8080/JSPWiki
  • Use your plugin on the page:
  • Or try the below with the bodyContent:

With __bold__ content