JSPWiki now (2.1.127+) includes the WikiFormsPlugin that allow simple html forms to be created on wiki pages. When the form is submitted the values are passed as parameters to a user defined 'handler' plugin which is invoked when the form is submitted.

This is actually a set of interrelated plugins, not just one.


First you start with...
  • FormSet - sets default form element values.
  • FormOutput - calls the designated handler and displays its output.
  • FormOpen - starts the form by emitting the html <form> tag.

Then you put any normal wikitext between the ~FormOpen and ~FormClose along with any number of the following form elements.

Finally you must end your form with...

  • FormClose - ends the form by emitting the html </form> tag.

And that's it, if you want you can define any number of forms on one page, just don't nest their ~FormOpen/~FormClose portions. When a form submit button is hit by the user the input/select/textarea elements are sent to the server where the handler gets invoked and the values are available as it's parameters.

The following example uses the form plugins to provide parameters to the CurrentTimePlugin, and displays the result.


The ~FormSet plugin sets the default date format for a form field format in form testform. This is hidden in normal WikiPage viewing, looks like this:
[{FormSet form='testForm' format='EEE, d MMM yyyy mm:ss:HH Z'}]


~FormOutput specifies that the 'handler' (here, the CurrentTimePlugin), should be used to generate some output to display here. While the output is usually built in response to a POST from a form called testform, the populate attribute here hints that we want default information shown (the plugin called) even if no post has yet been made.
[{FormOutput form='testForm' handler='CurrentTimePlugin' populate='handler'}]
Sun, 24 Oct 2021 10:54:19 +0000


The third element starts the actual HTML form called testform, there is no visible output from this.
[{FormOpen form='testform'}]


Text fields#

We'll use a text field to provide the format of CurrentTimePlugin's output. Notice that the name of this field is format - the name of CurrentTimePlugin's relevant parameter. This value is passed straight to CurrentTimePlugin on submit:
[{FormInput type='text' name='format'}]
Enter the time format string: Plugin insertion failed: Plugin failed

The rest of this form merely demonstrates the other HTML form elements. They don't mean anything to the CurrentTimePlugin of course, but just for fun here's what they look like.


[{FormInput type='checkbox' name='orderSpam' value='spam'}] Spam!\\
[{FormInput type='checkbox' name='orderParrot' value='parrot'}] Dead parrot.\\
[{FormInput type='checkbox' name='orderLumber' value='lumber'}] Lumberjack.\\
Plugin insertion failed: Plugin failed Spam!
Plugin insertion failed: Plugin failed Dead parrot.
Plugin insertion failed: Plugin failed Lumberjack.

Radio buttons#

Notice that all radio button elements share the same name, that's how you can 'group' them if you want multiple sets.

You can set the default checked item using checked='on|true|yes'. (In versions past 2.2.33 the value may also include the XHTML value of 'checked'.)

[{FormInput type='radio' name='favoriteActor' value='jones'}] Terry Jones
[{FormInput type='radio' name='favoriteActor' value='chapman' checked='true'}] Graham Chapman
[{FormInput type='radio' name='favoriteActor' value='cleese'}] John Cleese
[{FormInput type='radio' name='favoriteActor' value='idle'}] Eric Idle
[{FormInput type='radio' name='favoriteActor' value='gilliam'}] Terry Gilliam
[{FormInput type='radio' name='favoriteActor' value='palin'}] Michael Palin
Plugin insertion failed: Plugin failed Terry Jones
Graham Chapman
Plugin insertion failed: Plugin failed John Cleese
Plugin insertion failed: Plugin failed Eric Idle
Plugin insertion failed: Plugin failed Terry Gilliam
Plugin insertion failed: Plugin failed Michael Palin

Submit buttons #

What good is a form if there isn't any way to submit it? You can of course put multiple submit buttons, each for differing actions the name parameter will be a key in the parameter Map passed to the plugin. The plugin can look for various keys to tell which button was used to do the form submission.
[{FormInput type='submit' name='updateButton' value='Update Button'}]
[{FormInput type='submit' name='differentButton' value='A Different Button'}]
Plugin insertion failed: Plugin failed Plugin insertion failed: Plugin failed


This allows you to define a drop-down selection list. Notice, the asterisk; this denotes the default value to be selected when displayed. The separator character (;) and the default character (*) can be overridden - check the JavaDocs of this plugin.
[{FormSelect name='breakfast' value='egg and spam;egg bacon and spam;*egg bacon sausage 
and spam;spam bacon sausage and spam;spam egg spam spam bacon and spam;'}]


Of course what good is a form without the abiltiy to have a multiline text area.

Please tell us why you like Monty Python

[{FormTextarea name='whyIlikeMontyPython' rows=5 cols=40}]