When set to on no form html will be written to the page. This is useful to set form parameters for form elements that use a different form, for instance with TWiki:Plugins.CommentPlugin. If used, the parameters name and action are not required.

-

-

noformhtml="on"

id

The id of the form. If not set, the name is used

-

the form name

id="thisformid"

validate

Set to "off" to disable form validation; overrules any FORMELEMENT validate parameters.

-

validation is enabled

validate="off"

passthrough

Sometimes, for example when redirecting to a login page during authentication (and then again from the login page to the original requested URL), you want to make sure all parameters are passed on, and for this passthrough should be set to on. In this case it will pass all parameters that were passed to the current query on to the redirect target. If the request method for the current query was GET, then all parameters will be passed by encoding them in the URL (after '?'). If the request_method was POST, then there is a risk the URL would be too big for the receiver, so it caches the form data and passes over a cache reference in the redirect GET. NOTE: passthrough is only meaningful if the redirect target is on the same server. Useful when creating forms for CommentPlugin - see FormPluginExamples.

-

off

passthrough="on"

topic

Only if action is set to view, viewauth, edit, upload, create or save: the target topic of the action. Webname.TopicName syntax may be used.

-

the current topic

topic="%WEB%.WebHome"

web

Only if action is set to view, viewauth, edit, create or save: the target web of the action.

-

the current web

web="Main"

anchor

The anchor link the form should be linked to after successful submission. In case of an error, the default notification anchor link is used to directly point to possible problems (anchor #FormPluginNotification).

The CSS class of the form container. Use CSS classes twikiFormSteps and twikiFormStep for elements to divide the form in steps.

-

-

formcssclass="twikiFormSteps"

elementcssclass

The CSS class of the element container. Use CSS class twikiFormStep class to divide the form in steps.

-

-

elementcssclass="twikiFormStep"

onSubmit

Function call that is invoked when the user has pressed the submit button of a form. This event happens just before the form is submitted, and your function can return a value of false in order to abort the submission. Note that the function call should include (this).

-

-

onSubmit="return notify(this)"

sep

HTML element separator; defaults to \n (TML line feed), but can be set to " " or similar to allow FORM to be defined within a table

-

"\n"

sep=" "

showerrors

Position of the error feedback: above the form (default), below, or off (hide). Use %FORMERROR% to display the message elsewhere.

-

"above"

showerrors="off"

noredirect

By setting this to "on", FormPlugin will not redirect after submitting a form (after validation failure or success).

-

-

noredirect="on"

FORMELEMENT

FORMELEMENT contains:

form field - see paramters below

optional items:

title

div container

hint text

mandatory indication

Use %URLPARAM{"element_name"}% to retrieve the value of a submitted form element.

Creates a variable sized selection box; use param size to set the visible number of items; use options to pass dropdown values, labels to set the option labels, and value to set the default selected values.

Creates a set of checkboxes; to put checkboxes on line each set fieldformat="$e <br />"; use options to pass dropdown values, labels to set the option labels, and value to set the default selected values.

Creates a set of radio buttons; to put radio buttons on line each set fieldformat="$e <br />"; use options to pass dropdown values, labels to set the option labels, and value to set the default selected values. See also param dateformat.

Predefined input: • For single entry elements: the text value. • For multi-select elements: the default selected items; a comma delimited string. • For type="submit" the button label; you may use buttonlabel as well.

Indicates if the form element needs to have a value or selection when the form is submitted. When submitted the field must not be empty. Creates a red asterisk (unless the format is defined differently).

-

-

mandatory="on"

validate

The type of entry this form element needs to have when the form is submitted: • nonempty single entry elements: must have a value; multi-select elements: must have a selection • string same as nonempty; this will not test if the input is a number, because for Perl there is no difference between string and number • int the input must be a rounded number • float the input accepts rounded numbers and floating point numbers • email the input must be in e-mail format

-

-

validate="nonempty"

condition

Conditionally sets the value value of a form field. Used together with value parameter and a form field token: $name_of_form_field. Use the same parameters as with validate.

-

-

This example will write a bullet item with the value of field date_from, only if that value exists: value=" * $date_from"condition="$date_from=nonempty"

Javascript parameters

(Javascript convenience method) Creates default text in a textfield that is 'clicked away' when the field is clicked.

-

-

beforeclick="Your name..."

onFocus

Function call that is invoked when the user has selected a field.

-

-

onFocus="makeBlack(this)"

onBlur

Function call that is invoked when the user has changed the part of a text field that is selected.

-

-

onBlur="makeGray(this)"

onMouseOver

Function call that is invoked when the mouse has moved over an element.

-

-

onMouseOver="makeYellow(this)"

onMouseOut

Function call that is invoked when the mouse has moved off an element.

-

-

onMouseOut="makeWhite(this)"

onSelect

Function call that is invoked when the user has changed the part of a text field that is selected.

-

-

onSelect="makeBold(this)"

onChange

Function call that is invoked when the user has changed the contents of a field.

-

-

onChange="giveFeedback(this)"

onKeyUp

Practically the same as onChange.

-

-

onKeyUp="giveFeedback(this)"

onClick

Function call that is invoked when the user has clicked an element.

-

-

onClick="beep(this)"

ENDFORM

Does not have any parameters.

FORMSTATUS

Retrieve the validation status of the form. Note that the status cannot be used to build form logic (the variable expansion happens long after the form is created), but you may use it to show additional feedback.

Download the ZIP file from the extension home on twiki.org (see below).

Unzip FormPlugin.zip in your twiki installation directory.

Set the ownership of the extracted directories and files to the webserver user.

Install the dependencies (if any).

Plugin configuration and testing:

Run the configure script and enable the plugin in the Plugins section.

Configure additional plugin settings in the Extensions section if needed.

Test if the installation was successful using the examples provided.

Plugin Info

Plugin Authors:

Arthur Clemens, Sven Dowideit, Eugen Mayer

Other authors:

Validate.pm, originally CGI::Validate by Zenin <zenin@archive.rhps.org> aka Byron Brummer <byron@omix.com>. Copyright (c) 1997,1998 OMIX, Inc. All rights reserved. Use is granted under the same terms of Perl.

New features: • In line of TWiki security policy, make POST the default submit method • Added support for REST calls: set the action to rest and set restaction• Added format parameter $a to set the location of the form element anchor link, useful for table layouts • Changed param allowredirects to noredirect• Pure text format textonly, no input element • Added warning if required data is not passed for STARTFORM or FORMELEMENT.

16 Mar 2009

1.4.6 Eugen Mayer: Added new option for STARTFORM, which allows to control the redirects ( allowredirects ).

29 Jan 2009

1.4.5 Moved javascript and css includes to template files to allow other js libs to be used.