The WikiFormsPlugin is a JSPWikiPlugin (actually a set of interrelated plugins, not a single plugin) that lets you build a simple HTML form on a WikiPage, and handle its posted data with a plugin. 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 can be useful if you wish to use your wiki as an interface for custom tasks.

Synopsis...#

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.

• FormInput - textbox, radio buttons, check boxes, submit button
• FormSelect - dropdown selection box
• FormTextarea - multiline textarea

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.

Example#

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

FormSet#

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#

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'}]

FormOpen#

The third element starts the actual HTML form called testform, there is no visible output from this.

[{FormOpen form='testform'}]

[{FormInput type='text' name='format'}]

[{FormInput type='text' name='name' value='value'}]

[{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.\\

[{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

[{FormInput type='submit' name='updateButton' value='Update Button'}]
[{FormInput type='submit' name='differentButton' value='A Different Button'}]

[{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;'}]

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

[{FormClose}]

What happens on submit?#

When you click on a submit button, the form is posted to the current page. All the Form inputs specified on the page are given to the WikiPlugin defined in the FormOpen invocation's handler parameter. The plugin receives the inputs in a Map of input name-value pairs (just like WikiPlugins always do), performs whatever logic it needs to do, and optionally provides output (see FormOutput). It may also adjust the submitted values.

The form is then redisplayed, with the submitted values (except where adjusted by the handler).

See: JSPWikiCorePlugins