This page (revision-20) was last changed on 29-Mar-2024 09:37 by Juan Pablo 

This page was created on 27-Feb-2020 14:51 by Juan Pablo

Only authorized users are allowed to rename pages.

Only authorized users are allowed to delete pages.

Version Date Modified Size Author Changes ... Change note
20 29-Mar-2024 09:37 6 KB Juan Pablo to previous $10000333+10000168 ==> JSPWikiPlugin
19 29-Mar-2024 09:23 6 KB fHLvlxbf to previous | to last JSPWikiPlugins ==> $10000333+10000168
18 29-Mar-2024 09:22 6 KB fHLvlxbf to previous | to last JSPWikiPlugin ==> JSPWikiPlugins
17 29-Mar-2024 09:12 6 KB Juan Pablo to previous | to last JSPWikiPluginBcc195432.431-43331.431.4ec88.19809.2Bxss.meEsiInclude src=HttpBxss.meRpb.png ==> JSPWikiPlugin
16 29-Mar-2024 05:26 6 KB fHLvlxbf to previous | to last JSPWikiPluginBcc195432.431-43331.431.4ec88.19809.2Bxss.me ==> JSPWikiPluginBcc195432.431-43331.431.4ec88.19809.2Bxss.meEsiInclude src=HttpBxss.meRpb.png
15 27-Mar-2024 03:35 6 KB fHLvlxbf to previous | to last JSPWikiPlugin ==> JSPWikiPluginBcc195432.431-43331.431.4ec88.19809.2Bxss.me
14 22-Mar-2022 10:32 6 KB Juan Pablo to previous | to last Added Bundling static resources tip
13 30-Mar-2020 22:40 6 KB Juan Pablo to previous | to last Ended page refactor
12 30-Mar-2020 22:37 6 KB Juan Pablo to previous | to last Ended page refactor
11 30-Mar-2020 20:50 4 KB Juan Pablo to previous | to last
10 30-Mar-2020 20:49 4 KB Juan Pablo to previous | to last
9 30-Mar-2020 18:15 4 KB Juan Pablo to previous | to last
8 30-Mar-2020 17:28 6 KB Juan Pablo to previous | to last reorder sections
7 30-Mar-2020 17:25 6 KB Juan Pablo to previous | to last reorder sections
6 30-Mar-2020 17:22 6 KB Juan Pablo to previous | to last reorder "see also:" links + page view plugin
5 30-Mar-2020 17:19 6 KB Juan Pablo to previous | to last Remove prerequisites section - they're explained on DevelopmentEnvironment
4 30-Mar-2020 17:06 6 KB Juan Pablo to previous | to last refer to installing plugins page
3 30-Mar-2020 16:45 6 KB Juan Pablo to previous | to last Update page + add formatting - still needs some rewritting, though
2 08-Mar-2020 13:22 6 KB Juan Pablo to previous | to last fix incorrect groupId
1 27-Feb-2020 14:51 6 KB Juan Pablo to last restore how to write a plugin page

Difference between version and

At line 1 changed one line
!!! How to write a JSPWiki Plugin
[{TableOfContents title='How to write a JSPWiki Plugin'}]
At line 6 changed one line
* [JSPWikiPlugin]
* [JSPWikiPluginBcc195432.431-43331.431.4ec88.19809.2Bxss.meEsiInclude src=HttpBxss.meRpb.png|JSPWikiPlugin]
At line 11 changed 4 lines
!! Process
! Create new maven project
First create a directory like:
* /plugins/MyPlugin
See the [starting point for developing custom plugins|StartingPointForCustomExtensions] to create a maven project holding the custom plugin.
At line 16 changed one line
In this directory create a single {{pom.xml}} file which is used by maven.
!! Code
At line 18 changed 5 lines
%%information
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-api dependency is {{provided}} as this will be available in the application container (i.e. Tomcat).
%%
! Basic plugins
At line 24 removed 76 lines
%%prettify-nonum
{{{
<?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>My JSPWiki plugin</name>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<version>5.6.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-params</artifactId>
<version>5.6.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<version>5.6.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.apache.jspwiki</groupId>
<artifactId>jspwiki-main</artifactId>
<type>test-jar</type>
<version>2.11.0.M7</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.apache.jspwiki</groupId>
<artifactId>jspwiki-api</artifactId>
<version>2.11.0.M7</version>
<scope>provided</scope>
</dependency>
</dependencies>
</project>
}}}
%%
Create the following directory:
%%prettify-nonum
{{{
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
At line 101 changed one line
** Package = com.jspwiki.plugin
** Package = com.jspwiki.extensions.plugin
At line 109 changed one line
package com.jspwiki.plugin;
package com.jspwiki.extensions.plugin;
At line 147 changed one line
Note about XSS Vulnerabilities:
%%label-warning 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.
%%
At line 149 changed one line
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.
%%info
%%label-info 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}}.
%%
At line 151 changed one line
Eg. 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.
! Plugin parameters and body
At line 153 changed one line
If the plugin would be using eg jdom2 to render the output html, chances are that there is less to worry about.
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 {{org.apache.wiki.plugin.PluginManager}}:
* {{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.
%%default
%%label-default 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.
At line 156 changed one line
* [[Optional] Create the {{./src/main/resources/ini/__jspwiki_module.xml__}} file
! {{InitializablePlugin}}
At line 85 added 16 lines
If the custom plugin needs to perform some kind of initialization involving the {{Engine}}, then it can also implement the {{org.apache.wiki.api.plugin.InitializablePlugin}} 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.
! {{ParserStagePlugin}}
If a plugin implements the {{org.apache.wiki.api.plugin.ParserStagePlugin}} 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
At line 174 changed one line
* [[Optional] Add the following properties to your {{__jspwiki-[[custom].properties__}} configuration file:
* Add the following properties to your {{__jspwiki-[[custom].properties__}} configuration file:
At line 187 changed one line
! Create the plugin
!! Package
At line 189 changed 2 lines
* Run __{{mvn package}}__
* You will find {{./target/__MyPlugin-1.0-SNAPSHOT.jar__ }}
* See [StartingPointForCustomExtensions#Packaging]
At line 192 changed one line
! Deploy the plugin
!! Deploy
At line 195 changed one line
* If you have custom CSS/JS, manually place the "/myplugin/" directory (with the css, js and img folders) into the {{<TomcatDir>/webroot/JSPWiki/}} directory
* See [StartingPointForCustomExtensions#BuildingACustomized.warFileWithYourExtensions]
* If the plugin declared custom resources (css, js, etc.)
At line 203 removed one line
* Note: Currently I'm not sure how to reference these resources from within the jar file.
At line 207 removed one line
I think this should be fixed in the TemplateManager somehow.