How to write a JSPWiki Plugin.
See also

• ContributedPlugins
• JSPWikiCorePlugins
• JSPWikiPlugin
• DevelopmentEnvironment

Prerequsites#

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

Install Eclipse#

• http://www.eclipse.org/

Install Tomcat#

• http://tomcat.apache.org/

Install Maven#

• http://maven.apache.org/

Process#

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.

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>com.jspwiki.plugin</groupId>
  <artifactId>MyPlugin</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Maven Quick Start</name>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.apache.jspwiki</groupId>
      <artifactId>jspwiki-war</artifactId>
      <version>2.10.1</version>
      <classifier>classes</classifier>
      <scope>provided</scope>
    </dependency>
  </dependencies>

</project>

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 org.apache.wiki.api.plugin.WikiPlugin;
  • implements WikiPlugin

package com.jspwiki.plugin;

import java.util.Map;

import org.apache.log4j.Logger;
import org.apache.wiki.WikiContext;
import org.apache.wiki.api.exceptions.PluginException;
import org.apache.wiki.api.plugin.WikiPlugin;
import org.apache.wiki.plugin.DefaultPluginManager;
import org.apache.wiki.ui.TemplateManager;

public class MyPlugin implements WikiPlugin {

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

	@Override
	public String execute(WikiContext wikiContext, Map<String, String> params) throws PluginException {
		log.info("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"?>
<modules>
   <plugin class="com.jspwiki.plugin.MyPlugin">
      <author>Your Name</author>
      <minVersion>2.10.1</minVersion>
      <!-- Only the above two lines are required -->
      <script>/myplugin/js/myplugin.js</script>
      <stylesheet>/myplugin/css/myplugin.css</stylesheet>
      <alias>My</alias>
   </plugin>
</modules>

• Create the /src/main/resources/log4j.properties configuration file:

log4j.logger.com.jspwiki.plugin.MyPlugin=INFO, stdout
log4j.additivity.com.jspwiki.plugin.MyPlugin=false

# Direct log messages to stdout
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
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#

• 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.

• Restart your tomcat
  • http://localhost:8080/JSPWiki
• Use your plugin on the page:

[{MyPlugin}]

• Or try the below with the bodyContent:

[{MyPlugin

With __bold__ content
}]

Download#

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

Source#

• HowToWriteAPlugin/MyPlugin.zip

Plugin#

• HowToWriteAPlugin/MyPlugin-1.0-SNAPSHOT.jar

---

Category.D