DocWiki2.4: DevelopingPlugins

More...

Writing your own plugin#

StubArticle

The main thing is that you must do is to implement the execute() -method of WikiPlugin.

Cfr. with Writing plugins doc at jspwiki main site
-- JP

Testing your plugin#

StubArticle

Deploying your plugin#

The jspwiki_module.xml#

Tampering with the jspwiki.plugin.searchPath -property is not the only way to deploy your plugins. In addition, you can also use the jspwiki_module.xml file. For example:

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

<modules>

   <plugin class="org.myorg.jspwiki.plugins.SamplePlugin">
      <author>Jack B. Smith</author>
      <script>sampleplugin.js</script>
      <stylesheet>sampleplugin.css</stylesheet>
      <alias>sample</alias>
      <minVersion>2.4</minVersion>
      <maxVersion>2.4.90</maxVersion>
   </plugin>

   <editor name="plain">
      <author>Janne Jalkanen</author>
      <path>editors/plain.jsp</path>
   </editor>

</modules>

Common attributes#

author : Author name.
minVersion : The minimum version of JSPWiki that your module works with.
maxVersion : The maximum version of JSPWiki that your module works with.

The version number should be of the form "x.y.z" (where y and z are optional). For example "2.4" would match every single release of JSPWiki 2.4. If you want to be more specific (like this works from version 2.4.56 onwards), just declare the entire version. The versioning feature is available from 2.4.58 onwards.

Plugin-specific attributes#

script: Determines a script to be included in the page each time this plugin is invoked.
stylesheet : Determines a stylesheet to be included in the page each time this plugin is invoked.
alias: An alias for the plugin. In the above example, you could also use [{sample}] instead of [{org.myorg.jspwiki.plugins.SamplePlugin}].

Editor-specific attributes#

Editors probably have a JSP-specific component that will need to be installed first. However, the jspwiki_modules.xml is used to determine where that editor is.

path: Where the editor is located with respect to the template directory. E.g. "editors/plain.jsp" would mean $JSPWIKI_HOME/templates/default/editors/plain.jsp.

Constructing your plugin JAR file#

JSPWiki is smart enough to find the jspwiki_module.xml file, if you put it in the "ini" -directory of your JAR file. For example, your JAR file could look like this:

% jar tvf sampleplugin.jar
 34172 Sun Jul 16 00:01:52 EEST 2006 META-INF/MANIFEST.MF
     0 Sun Jul 16 00:01:44 EEST 2006 META-INF/
     0 Tue Jun 27 10:33:28 EEST 2006 org/
     0 Tue Jun 27 10:33:28 EEST 2006 org/myorg/
     0 Tue Jun 27 10:33:32 EEST 2006 org/myorg/jspwiki/
     0 Tue Jun 27 10:33:32 EEST 2006 org/myorg/jspwiki/plugins/
  6794 Tue Jun 27 10:33:28 EEST 2006 org/myorg/jspwiki/plugins/SamplePlugin.class
     0 Tue Mar 28 19:18:16 EEST 2006 ini/
   635 Tue Mar 28 19:18:16 EEST 2006 ini/jspwiki_module.xml

Now, you can put the sampleplugin.jar anywhere in your classpath, and JSPWiki will pick up the plugin - no modification to the jspwiki.properties is necessary!

Questions:#

Q: Can I have multiple <plugin> declarations in on jspwiki_module.xml ?

A: Yes.

Q: If I add an editor declaration, will it be available on all JSPWiki pages or just on pages that use one of the associated plugins?

A: Yes, it will be available on all pages.

Sometimes the plugin can be configured using a property file (for instance the Code2Html plugin). Is there a standard location for this property file? Is there a standard way to process this file?

--Arno Brouwer, 17-May-2010 10:48