FormPlugin < System

%IF{"defined Name and $ Name != ''" then="---+!! Hello %URLPARAM{"Name"}%!" else="---+!! Form Plugin"}%
*Lets you create simple and advanced web forms.*

Main features:
   * No html knowledge required to create forms
      * Add input fields, textareas, dropdown select boxes, checkboxes, radio buttons
      * Set preselected values
   * Call Foswiki scripts (view, edit, upload, save, etcetera) or custom scripts
   * Validate the form before it is sent along
   * Get inline validation without additional coding
   * Use entered field values as variables
   * Add Javascript functions for advanced interaction

Example of inline validation feedback:

<div class="foswikiImage"><img src="%ATTACHURLPATH%/screenshot_validation_example.png" alt="Example of validation error feedback" width='664' height='434' /></div>

See examples in [[Sandbox.FormPluginExamples]].

%TOC%

---++ Introduction
A simple form can be created like this:
<verbatim>
%STARTFORM{
	name="myform"
	action="view"
}%%FORMELEMENT{
	name="Name"
	type="text"
	title="Your name:"
	mandatory="on"
}%%FORMELEMENT{
	name="action"
	type="submit"
	buttonlabel="Submit"
}%%ENDFORM%
</verbatim>

%IF{"not context FormPluginEnabled" then="<!--"}%
This results in:

%STARTFORM{
	name="myform"
	action="view"
}%%FORMELEMENT{
	name="Name"
	type="text"
	title="Your name:"
	mandatory="on"
}%%FORMELEMENT{
	name="action"
	type="submit"
	buttonlabel="Submit"
}%%ENDFORM%
%IF{"not context FormPluginEnabled" then="-->"}%

%IF{"not context FormPluginEnabled" then='This plugin is %RED%not enabled%ENDCOLOR% so the form is not created.'}%

---++ Usage
<verbatim>
%STARTFORM{
   name="..."
   action="..."
   restaction="..."
   method="..."
   id="..."
   validate="..."
   inlinevalidationonly="..."
   serversidevalidationonly="..."
   substitute="..."
   topic="..."
   web="..."
   anchor="..."
   redirectto="..."
   formcssclass="..."
   elementcssclass="..."
   elementformat="..."
   noformhtml="..."
   onSubmit="..."
   sep="..."
   showerrors="..."
   noredirect="..."
   disabled="..."
}%
%FORMELEMENT{
   name="..."
   type="..."
   title="..."
   hint="..."
   mandatory="..."
   validate="..."
   condition="..."
   options="..."
   labels="..."
   value="..."
   buttonlabel="..."
   size="..."
   maxlength="..."
   rows="..."
   cols="..."
   format="..."
   titleformat="..."
   cssclass="..."
   focus="..."
   disabled="..."
   readonly="..."
   placeholder=..."
   onFocus="..."
   onBlur="..."
   onMouseOver="..."
   onMouseOut="..."
   onSelect="..."
   onChange="..."
   onClick="..."
   onKeyUp="..."
}%
%ENDFORM%
</verbatim>

Most parameters are optional. See below for a detailed explanation.

---++ Parameters
---+++ STARTFORM

%TABLE{columnwidths="10%,35%,10%,10%,35%"}%
| *Parameter* | *Description* | *Required* | *Default value* | *Example* |
| =name=      | The name of the form. Must be unique. Will also be used as the id, if =id= is not provided | required |=-=| =name="personaldata"= |
| =action=    | Action of the form. For example: %BR%\
 =view=, =viewauth=, =edit=, =save=, =create=, =rest=, =%<nop>SCRIPTURL{view}%/%<nop>WEB%/WebHome= | required |=-=| =action="viewauth"= |
| =restaction=    | If =action= is =rest=: the rest function to call; see System.CommandAndCGIScripts. |if =action= is =rest= |=-=| =restaction="<nop>MyPlugin/update"= |
| =noformhtml= | 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 Foswiki:Extensions.CommentPlugin. If used, the parameters =name= and =action= are not required. |=-=|=-=| =noformhtml="on"= |
| =id=  | The id of the form.  |-  |- | =id="thisformid"= | 
| =validate=  | Set to ="off"= to disable form validation; overrules any FORMELEMENT =validate= parameters. By default forms are validated, and field values checked for possible subsitution values (see <a href='#ValueSubstitution'>Substitution of field references</a>).  |-  |=on= | =validate="off"= | 
| =inlinevalidationonly=  | Together with =validate="on"=: set to ="on"= to disable server-side (backend) validation: only inline validation using javascript is used. This means that when javascript is not enabled on the client machine, no validation will take place, and no redirection to the current topic (there is no validation to fail). Note that inline validation can be bypassed and is not secure. For operation critial forms always use server-side validation as well (and do not use this setting). |-  | =off=: server-side validation is enabled when =validate="on"= | =inlinevalidationonly="on"= |
| =serversidevalidationonly= | Together with =validate="on"=: set to ="on"= to disable inline (frontend) validation: only server-side (backend) validation is performed. |- | =off=: inline validation is enabled when =validate="on"= | =serversidevalidationonly="on"= |
| =substitute= | Set to ="on"= if you need to perform subsitution of field references (see <a href='#ValueSubstitution'>Substitution of field references</a>), but do not want/need to validate the form. |- |- | =substitute="on"= (and =validate="off"=) |
| =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="%<nop>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. %BR% \
In case of an error, the default notification anchor link is used to directly point to possible problems (anchor =#<nop>FormPluginNotification=). |=-=| | =anchor="MyForm"= |
| =method=    | =get= or =post= ([[http://www.cs.tut.fi/~jkorpela/forms/methods.html][What's the difference?]]) |=-=| =post= | =method="post"= |
| =redirectto= | Redirect topic after form action has been performed. |=-=|=-=| =redirectto="Main.WebHome"= |
| =formcssclass= | The CSS class of the form container. Use CSS classes =foswikiFormSteps= and =foswikiFormStep= for elements to divide the form in steps. |=-=|=-=| =formcssclass="foswikiFormSteps"= |
| =elementcssclass= | The CSS class of the element container. Use CSS class =foswikiFormStep= class to divide the form in steps. |=-=|=-=| =elementcssclass="foswikiFormStep"= |
| =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). |=-=| ="above"= | =showerrors="off"= |
| =noredirect= | By setting this to "on", !FormPlugin will not redirect after submitting a form (after validation failure or success). |=-=|=-=| =noredirect="on"= |
| =disabled= | Set to ="on"= to disable all fields. Can be overridden with FORMELEMENT =disabled="off"=. |=-=|=-=| =disabled="on"= |

---+++ FORMELEMENT

=FORMELEMENT= contains:
   * form field - see parameters below
   * optional items:
      * title
      * div container
      * hint text
      * mandatory indication

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

---++++ Attributes
%TABLE{columnwidths="10%,35%,10%,10%,35%"}%
| *Parameter*     | *Description* | *Required* | *Default value* | *Example* |
| =name=          | Element name, must be unique to the form. Spaces and punctuation should be avoided (due to possible encoding issues, and they won't work when using value subsitution). The element name is used in the server-side validation error feedback. | required |=-=| =name="First_name"= |
| =type=          | Type of the element - see below for possible types. |required|=-=||
| =type="text"=   | Creates a textfield; use =size= and =maxlength= to set the length. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="comment" %BR% \
type="text" %BR% \
title="Comment" %BR% \
}%= |
| =type="textonly"= | Does not use a form field but writes the value as text inside an HTML =span= with class =formPluginTextOnly=. The value is passed when submitting the form using a hidden field. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="name" %BR% \
type="textonly" %BR% \
value="%<nop>WIKIUSERNAME%" %BR% \
}%= |
| =type="password"=   | Creates a password textfield; otherwise same as =text=. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="pw" %BR% \
type="password" %BR% \
}%= |
| =type="upload"=   | Creates an upload field; use with =STARTFORM= parameter =action="upload"= and set the =name= to ="filepath"=. |=-=|=-=| =%<nop>STARTFORM{ %BR% \
name="uploadpicture" %BR% \
action="upload" %BR% \
topic="%<nop>WEB%.%<nop>TOPIC%" %BR% \
method="post" %BR% \
}% %BR% \
%<nop>FORMELEMENT{ %BR% \
type="upload" %BR% \
name="filepath" %BR% \
title="Attach profile picture" %BR% \
}% %BR% \
...= |
| =type="textarea"=   | Creates a textarea; use params =rows= and =cols= to set the size. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="body" %BR% \
type="textarea" %BR% \
title="Message:" %BR% \
rows="5" %BR% \
cols="80" %BR% \
}%= |
| =type="select"=   | 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. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="friend" %BR% \
type="select" %BR% \
size="5" %BR% \
title="Select friend:" %BR% \
options="mary, peter, annabel, nicky, jennifer" %BR% \
labels="Mary M, Peter P, Annabel A, Nicky N, Jennifer J" %BR% \
}%= |
| =type="selectmulti"=   | Same as =select= with multiple items selectable; use =options= to pass dropdown values, =labels= to set the option labels, and =value= to set the default selected values. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="friends" %BR% \
type="selectmulti" %BR% \
size="5" %BR% \
title="Select friends:" %BR% \
options="mary, peter, annabel, nicky, jennifer" %BR% \
labels="Mary M, Peter P, Annabel A, Nicky N, Jennifer J" %BR% \
value="mary,annabel" %BR% \
}%= |
| =type="dropdown"=   | Same as =select= with 1 item visible; use =options= to pass dropdown values, =labels= to set the option labels, and =value= to set the default selected value. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="friend" %BR% \
type="dropdown" %BR% \
title="Select friend:" %BR% \
options="mary, peter, annabel, nicky, jennifer" %BR% \
labels="Mary M, Peter P, Annabel A, Nicky N, Jennifer J" %BR% \
value="peter" %BR% \
}%= |
| =type="checkbox"=   | Creates a set of checkboxes; use =cssclass="formPluginInlineLabels"= to draw labels on one line; use =options= to pass dropdown values, =labels= to set the option labels, and =value= to set the default selected values. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="name" %BR% \
type="checkbox" %BR% \
title="Choose a name:" %BR% \
options="mary=Mary M, peter=Peter P, annabel=Annabel A, nicky=Nicky N, jennifer=Jennifer J" %BR% \
value="mary,peter" %BR% \
}%= |
| =type="radio"=   | Creates a set of radio buttons; use =cssclass="formPluginInlineLabels"= to draw labels on one line;  use =options= to pass dropdown values, =labels= to set the option labels, and =value= to set the default selected values. See also param =dateformat=. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="name" %BR% \
type="radio" %BR% \
title="Choose a name:" %BR% \
options="mary=Mary M, peter=Peter P, annabel=Annabel A, nicky=Nicky N, jennifer=Jennifer J" %BR% \
value="mary" %BR% \
}%= |
| =type="date"=   | Creates a date button; requires !JSCalendarContrib (installed by default). |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="date" %BR% \
type="date" %BR% \
dateformat="%e-%b-%y" %BR% \
title="Select date:" %BR% \
}%= |
| =type="submit"=   | Creates a submit button. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="action" %BR% \
type="submit" %BR% \
buttonlabel="Send info" %BR% \
}%= |
| =type="hidden"=   | Creates a hidden input field. |=-=|=-=| =%<nop>FORMELEMENT{ %BR% \
name="CarbonCopy" %BR% \
type="hidden" %BR% \
default="$Name earns $Salary" %BR% \
}%= |
| =options=       | List of selectable value parameters to use with =select=, =dropdown=, =checkbox= or =radio=. You may use DataForms notation =option1=Label 1, option2=Label 2=. |=-=|=-=| =options="mary, peter, annabel, nicky, jennifer"= %BR% \
or %BR% \
=options="mary=Mary M, peter=Peter P, annabel=Annabel A, nicky=Nicky N, jennifer=Jennifer J"= |
| =labels=    |To use with =options=: list of visible labels for each option. |=-=|If no labels are set, the option values are displayed. | =labels="Mary M, Peter P, Annabel A, Nicky N, Jennifer J"= |
| =value=   |Predefined input: \
%BB% For single entry elements: the text value. \
%BB% For multi-select elements: the default selected items; a comma delimited string. \
%BB% For =type="submit"= the button label; you may use =buttonlabel= as well.  |=-=|=-=| =value="%<nop>WIKIUSERNAME%"= %BR% \
or %BR% \
=value="mary, peter, annabel"= %BR% \
or %BR% \
=value="Submit"= |
| =buttonlabel= | The button label. |=-=|=-=| =buttonlabel="Submit"= |
| =hint=      | Input hint optionally displayed next to the form element. |=-=|=-=| =hint="Enter a <nop>%SYSTEMWEB%.WikiWord"= |
| =mandatory= | Visual indicator 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 in the =format= parameter no =$m= token is defined). |=-=|=-=| =mandatory="on"= |
| =validate=  | Validation method (string) or rule (JSON string); see <a href="#FormValidation">Form validation</a>. |=-=|=-=| =validate="required"= |
| =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=. See <a href="#ConditionalValues">Conditional values</a>. |=-=|=-=| This example will write a bullet item with the value of field =date_from=, only if that value exists: %BR% \
=value="   * $date_from"= %BR% \
=condition="$date_from=nonempty"= |
| =format= | See [[#Formatting][Formatting]] below. ||| =format=" &lt;b&gt;$t&lt;/b&gt; $m $h $e"= |
| =elementformat= | See [[#Formatting][Formatting]] below. ||| =elementformat="$e &lt;br /&gt;"= |
| =titleformat= | See [[#Formatting][Formatting]] below. ||| =titleformat=" &lt;b&gt;$t&lt;/b&gt; &lt;br /&gt;"= |
| =cssclass=  | CSS class for the element |=-=|CSS classes: =foswikiInputField=, =foswikiSubmit= | =cssclass="foswikiBroadcastMessage"= |
| =size=   | For =type="text"= or =type="password"=: the width of the input field measured in number of characters. |=-=|=40= | =size="60"= |
| =maxlength=  | For =type="text"= or =type="password"=: the maximum number of input characters. |=-=|=-=| =maxlength="12"= |
| =rows=   | For =type="textarea"=: the number of rows. |=-=|=-=| =rows="5"= |
| =cols=   | For =type="textarea"=: the number of columns. |=-=|=-=| =cols="80"= |
| =disabled=  | =disabled="on"= disables user input; copying from a disabled input field is not possible. Note: disabled fields are not included into the submitted data. |=-=|=-=| =disabled="on"= |
| =readonly=  | =readonly="on"= makes the field read-only; copying is possible but not changing. Only works for text fields and textarea. Note: readonly fields _are_ included into the submitted data. |=-=|=-=| =readonly="on"= |
| =dateformat=   | Sets the output format of the date button, for instance: =%Y/%m/%d= - see [[#DateFormats][date formats]] for more info. |=-=| Default date format set in [[%SCRIPTURL{configure}%#JSCalendarContrib$Extensions][configure:JSCalendarContrib]]. ||
| =focus=  | <a name="focus"></a> =focus="on"= gives text entry focus to a field. Requires javascript. Only one element on the page can have focus. |=-=|=-=| =focus="on"= |
| =placeholder=  | Creates a 'hint' or 'example' text in a textfield that disappears when the field has focus or has custom input text. |=-=|=-=| =placeholder="Your name..."= |
| =beforeclick= | Deprecated: use =placeholder=. | | | |

---++++ Javascript parameters
Note that all function calls should include =(this)=.

%TABLE{columnwidths="10%,44%,8%,8%,30%"}%
| *Parameter* | *Description* | *Required* | *Default value* | *Example* |
| =onFocus=  | Function call that is invoked when the user has selected a field, either by clicking or tabbing. See also <a href="#focus">focus</a>. |=-=|=-=| =onFocus="makeBlack(this)"= |
| =onBlur=  | Function call that is invoked when the selected field is left. |=-=|=-=| =onBlur="makeGray(this)"= |
| =onMouseOver=  | Function call that is invoked when the mouse has moved over a field. |=-=|=-=| =onMouseOver="makeYellow(this)"= |
| =onMouseOut=  | Function call that is invoked when the mouse has moved off a field. |=-=|=-=| =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 a field. |=-=|=-=| =onClick="beep(this)"= |

---+++ ENDFORM
Required to close the form. Does not have any parameters.

---++ Retrieving form values
Use [[%SYSTEMWEB%.VarURLPARAM][%<nop>URLPARAM{}%]] to display submitted form values. For example
<verbatim>
   * Name = %URLPARAM{"MyName"}%
   * Names = %URLPARAM{"MyFriends" multiple="on" separator=", "}%
</verbatim>

---++ Formatting
Formatting of each form element can be set with the =FORMELEMENT= parameters:
   * =format= - defines the display of:
      * title
      * field
      * hint
      * mandatory indicator
   * =elementformat= - defines the display of the field / select item only
   * =titleformat= - defines the display of the title only

Use the following tokens to define where form element parts are displayed:
   * =$e= - form element token
   * =$t= - title token
   * =$h= - hint token
   * =$m= - mandatory token, currently just an asterisk =*=
   * =$a= - anchor token, where the anchor link should be placed (anchor links are used to link to fields with error feedback)

The escape tokens =$quot= ("), =$percnt= (%), =$dollar= ($), =$n= (newline) and =$nop= (&lt;nop&gt;) can be used to prevent expansion.

---+++ =format=
Attribute of =FORMELEMENT=, sets the format of the current field. Overrides the default format and the =elementformat= param set to =STARTFORM=.

The default =format= is defined in =templates/formplugin.tmpl=: 
<verbatim>
<div class="formPluginField"> $a $titleformat $e $m $h </div>
</verbatim>
=titleformat= is substituted with the value of <a href="#TitleFormat">titleformat</a>.

To switch the order around use for example:
<verbatim>
format="<div class="formPluginField"> $m $t $h <br />$e </div>"
</verbatim>

---+++ =elementformat=
Attribute of =STARTFORM=. Sets the default of each element format. The default =elementformat= is simply
<verbatim>
$e
</verbatim>

This means that radio buttons and checkboxes are all displayed on one line. To put these items on one line each, write:
<verbatim>
elementformat="$e <br />"
</verbatim>

<a name="TitleFormat"></a>
---+++ =titleformat=
Attribute of =FORMELEMENT=. The default =titleformat= is
<verbatim>
 $t <br />
</verbatim>

To display the title in bold, write:
<verbatim>
titleformat=" *$t* <br />"
</verbatim>

#DateFormats
---+++ Date Formats
Attribute of =FORMELEMENT= when =type="date"= is used. Possible format specifiers:
<verbatim>
%a - abbreviated weekday name 
%A - full weekday name 
%b - abbreviated month name 
%B - full month name 
%C - century number 
%d - the day of the month ( 00 .. 31 ) 
%e - the day of the month ( 0 .. 31 ) 
%H - hour ( 00 .. 23 ) 
%I - hour ( 01 .. 12 ) 
%j - day of the year ( 000 .. 366 ) 
%k - hour ( 0 .. 23 ) 
%l - hour ( 1 .. 12 ) 
%m - month ( 01 .. 12 ) 
%M - minute ( 00 .. 59 ) 
%n - a newline character 
%p - "PM" or "AM"
%P - "pm" or "am"
%S - second ( 00 .. 59 ) 
%s - number of seconds since Epoch (since Jan 01 1970 00:00:00 UTC) 
%t - a tab character 
%U, %W, %V - the week number
   The week 01 is the week that has the Thursday in the current year,
   which is equivalent to the week that contains the fourth day of January. 
   Weeks start on Monday.
%u - the day of the week ( 1 .. 7, 1 = MON ) 
%w - the day of the week ( 0 .. 6, 0 = SUN ) 
%y - year without the century ( 00 .. 99 ) 
%Y - year including the century ( ex. 1979 ) 
%% - a literal % character 
</verbatim>
For example, to get the date formatted as "2009-01-31", specify: =dateformat="%Y-%m-%d"=.

---++ Form processing
A !FormPlugin form is first processed before it is sent to its action target. Processing is done in 2 steps:
   1 Validation
   1 Substitution of field references

<div class="foswikiImage"><img src="%ATTACHURLPATH%/form_on_submit_diagram.png" alt="" width='804' height='502' /></div>

#ValueSubstitution
---+++ Substitution of field references
Value substitution changes field values so that the string =$To= is substituted with the value of field =To=. This way you can use field names as variables.

An example form that uses substitution:

<verbatim>
%STARTFORM{
	name="mail"
	action="view"
	topic="%WEB%.%TOPIC%"
	validate="off"
	substitute="on"
}%%FORMELEMENT{
	type="text"
	name="To"
}%%FORMELEMENT{
	type="hidden"
	name="Subject"
	value="email to $To"
	mandatory="on"
}%%FORMELEMENT{
	type="submit"
	name="submit"
	buttonlabel="Submit"
}%%ENDFORM%

Subject is: %URLPARAM{"Subject"}%
</verbatim>

When =validate="on"= (the default), substitution takes place automatically. 

#ConditionalValues
---+++ Conditional values
=FORMELEMENT= parameter =condition= allows to set a value only if the validation condition is met. The value is empty if the condition is not met.

Syntax:
=$field name=validation method=

The validation method uses the same syntax as form validation.

Assuming a field with name =Name= exists, field =Subject= will have the value of =Name= plus a bullet if the value of =Name= is a number:
<verbatim>
%FORMELEMENT{
   name="Subject"
   type="hidden"
   value="   * $Name"
   condition="$Name=number"
}%
</verbatim>

#FormValidation
---+++ Form validation
Form validation is done using inline validation and server-side validation, by default both methods are used.

Options for =STARTFORM=:
   * =inlinevalidationonly="on"= - only use inline validation
   * =serversidevalidationonly="on"= - only use server-side validation
   * =validate="off"= - turn off all validation

Inline validation adds Javascript to the page (it requires !JQueryPlugin's =validate= plugin).

Server-side validation uses the same methods and notation as !JQueryPlugin's =validate=, plus a couple of shortcut notations (including support for validation notation prior to version 2.0 of !FormPlugin).

The benefit of the more elaborate JSON notation is that multiple validation methods can be used, each with its own feedback message.

!JSON notation:
<verbatim>
validate="{
	rules: {
		required : true
	},
	messages: {
		required : 'You must enter a value'
	}
}"
</verbatim>
Notes:
   * JSON notation accepts method names without quotes
   * Use single quotes for strings, or use escaped double quotes
   * The value =true= must not be quoted
   * Use ={n}= tokens to write the prerequisite values to the string, see next example
   * If no messages are specified, default messages are written

Elaborate JSON notation:
<verbatim>
validate="{
	rules: {
		required : true,
		minlength : 2
	},
	messages: {
		required : 'We need your email address to contact you',
		minlength : 'At least {0} characters required!'
	}
}"
</verbatim>

Supported methods
   * =required=
   * =minlength: n=
   * =maxlength: n=
   * =equalto: field name= 
   * =rangelength: n=
   * =min: n=
   * =max: n=
   * =range: n1,n2=
   * =email=
   * =url=
   * =number=
   * =digits=
   * =creditcard=
   * =accept: string1,string2,string3=
   * =int=
   * =float=
   * =string=
   * =wikiword=

Shortcut notation:
   * =validate="required"= - must have a value
   * =validate="number"= - must have a value and must be a number

Former but still supported notation:
   * =validate="nonempty"= - single entry elements: must have a value; multi-select elements: must have a selection
   * =validate="string"= - same as =nonempty=
   * =validate="int"= - must have a value and must be a rounded number
   * =validate="float"= - must have a value and must be a number
   * =validate="email"= - must have a value and must be in e-mail format 

If a validation error occurs, the form is displayed with error feedback.

---++ Examples
See [[Sandbox.FormPluginExamples]]

#PluginTest
---++ Plugin Tests
   * This plugin is %IF{"context FormPluginEnabled" then='%GREEN%enabled%ENDCOLOR%' else ='%RED%not enabled%ENDCOLOR%'}%.

---++ CSS classes

| *Class name* | *Note* |
| =.formPluginField= | Wrapper around each field, including title and hint. Used by inline validation to position error messages. |
| =.formPluginNotification=  | Used for validation error feedback  |
| =fieldset.formPluginGroup=  | To group checkboxes and radio buttons  |
| =fieldset.formPluginGroupWithHint=  | A group with an input hint - shows a border at the right  |
| =.formPluginTitle= | Element title |
| =.formPluginError=  | State that causes input fields to have a red border and titles to be bold red  |
| =.formPluginHint=  | Input hint  |
| =.formPluginMandatory=  | Mandatory indication (asterisk)  |
| =.formPluginInlineLabels= | If set in =cssclass= of =FORMELEMENT=, draws fieldset labels inline, so on one line. | 

---++ Installation
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

---++ Plugin Info

|  Copyright: | &copy; 2007-2011 Arthur Clemens, Sven Dowideit, [[Foswiki:Main.EugenMayer][Eugen Mayer]] |
|  Version: | 11594 (2011-04-30) |
|  Release: | 2.0 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  30 Apr 2011 | 2.0 Complete code rewrite into modular files. %BR% \
Added inline validation with the additional options to only have inline validation or server-side validation. Inline validation settings will generate jQuery validation Javascript code. In case the client does not have Javascript, server-side validation will take place using the same checks as jQuery validation, which includes many more options than the previous validation code. %BR% \
=tabindex= is now automatically inserted based on the order of the form fields. %BR% \
Deprecated =beforeclick= for =placeholder=. %BR% \
No longer implemented: =FORMSTATUS= and =FORMERROR=. %BR% \
Many bugs fixed. |
|  02 Jun 2010 | 1.6.3 Fixed field reference substitution for !SendEmailPlugin. |
|  31 May 2010 | 1.6.2 Fixed field reference substitution when saving a topic; improved CSS in error messages. |
|  26 May 2010 | 1.6.1 Replaced =getRequestObject= with =getCgiQuery= to be compatible with Foswiki 1.0.9. |
|  26 May 2010 | 1.6 Arthur Clemens: %BR%\
Bug fixes: \
%BB% Fixed pre-selecting multiple items in multi-select form elements. \
%BB% All Foswiki scripts are now allowed in =action=. \
%BB% Fixed redirecting a topic and passing data in GET instead of POST. %BR%%BR%\
More: %BR%\
Complete unit testing. %BR% \
Messages are now set in template =formplugin.tmpl=, making them easier to change. %BR% \
Improved documentation. |
|  24 Aug 2009 | 1.5 Arthur Clemens: %BR%\
Bug fixes: \
%BB% Fixed checked value of radio button - sometimes did not get checked \
%BB% Fixed bug 0 value ignored \
%BB% Improved formatting for forms inside tables %BR% \
%BR% \
New features: \
%BB% In line of Foswiki security policy, make POST the default submit method \
%BB% Added support for REST calls: set the action to =rest= and set =restaction= \
%BB% Added format parameter =$a= to set the location of the form element anchor link, useful for table layouts \
%BB% Changed param =allowredirects= to =noredirect= \
%BB% Pure text format =textonly=, no input element \
%BB% 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. |
|  23 Jan 2009 | 1.4.4 added =id= for forms |
|  20 Jan 2009 | 1.4.2 added =tabindex= - Arthur Clemens |  
|  20 Jan 2009 | 1.4 added =sep=""=, =showerrors=""= and =%<nop>FORMERROR%= and fixes for Foswiki v1.0.0 - Foswiki:Main.SvenDowideit |
|  07 Jan 2009 | 1.3 Foswiki release. |
|  08 Mar 2008 | 1.2 Added =condition=, =noformhtml= and =dateformat= attributes. |
|  19 Oct 2007 | 1.1 Added =date= type. |
|  09 Jun 2007 | 1.0.5 Added upload parameter; option to turn off form validation; custom javascript has been replaced by code in =pub/System/<nop>JavascriptFiles/foswikiForm.js=; added Flickr example. |
|  27 May 2007 | 1.0.4 Update javascript calls to new =foswikiForm.js=. |
|  19 May 2007 | 1.0.3 Added element attributes: =focus=, =disabled=, =readonly=; Javascript parameters =beforeclick=, =onFocus=, =onBlur=, =onMouseOver=, =onMouseOut=, =onSelect=, =onChange=, =onClick=, =onKeyUp=; form parameter =onSubmit=. Fallback for form POSTs and TWiki versions earlier than 4.2: POST requests are converted to GET requests. |
|  15 May 2007 | 1.0.2 Added form attribute =elementformat=; changed parameter names for consistency: =class= to =cssclass=, =elementformat= to =elementformat=.  |
|  13 May 2007 | 1.0 First release. |
|  Dependencies: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">Regexp::Common</td><td align="left">&gt;=2011041701</td><td align="left">optional. Available from the CPAN archive.</td></tr><tr><td align="left">Foswiki::Plugins::JQueryPlugin</td><td align="left">&gt;=4.04</td><td align="left">Required</td></tr></table> |
|  Perl Version: | 5.005 |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |
|  Feedback: | http://foswiki.org/Extensions/%TOPIC%Dev |
|  Support: | http://foswiki.org/Support/%TOPIC% |

__Related Topics:__ %SYSTEMWEB%.DefaultPreferences, %USERSWEB%.SitePreferences, [[%SYSTEMWEB%.Plugins][Plugins]]
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
gif	error.gif	manage	0.3 K	30 Apr 2011 - 20:28	AdminUser
png	form_on_submit_diagram.png	manage	54.3 K	30 Apr 2011 - 20:28	AdminUser	Form on submit diagram
css	formplugin.css	manage	1.3 K	30 Apr 2011 - 20:28	AdminUser
png	screenshot_validation_example.png	manage	96.3 K	30 Apr 2011 - 20:28	AdminUser	Example of validation error feedback
This topic: System > Plugins > FormPlugin
Topic revision: revision 3 (raw view)
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback