Form Plugin

Lets you create simple and advanced web forms

Page contents

• Main features
• Introduction
• Usage
• Parameters
  • STARTFORM
  • FORMELEMENT
    • Attributes
    • Javascript parameters
  • ENDFORM
  • FORMSTATUS
  • FORMERROR
• Retrieving form values
• Formatting
  • format
  • elementformat
  • titleformat
  • Date Formats
• Form processing
  • Substitution of field references
  • Form validation
• Examples
• Plugin Settings
• Plugin Tests
• CSS classes
• Installation
• Plugin Info

Main features

• No html knowledge required to create forms
  • Add input fields, textareas, dropdown select boxes, checkboxes, radio buttons
  • Set preselected values
• Create a uniform layout
• Call TWiki scripts (view, edit, upload, save, etcetera) or custom scripts
• Use entered field values as variables
• Validate the form before it performs its action
  • Usability tested error feedback
• Add Javascript functions for advanced interaction

Example of validation error feedback:

Introduction

A simple form can be created like this:

%STARTFORM{
name="myform"
action="view"
}%
%FORMELEMENT{
name="Name"
type="text"
title="Your name:"
mandatory="on"
}%
%FORMELEMENT{
name="action"
type="submit"
buttonlabel="Submit"
}%
%ENDFORM%

This results in:

Your name:
*

Usage

%STARTFORM{
   name="..."
   action="..."
   restaction="..."
   method="..."
   id="..."
   validate="..."
   topic="..."
   web="..."
   anchor="..."
   redirectto="..."
   formcssclass="..."
   elementcssclass="..."
   elementformat="..."
   noformhtml="..."
   passthrough="..."
   onSubmit="..."
   sep="..."
   showerrors="..."
   noredirect="..."
}%
%FORMELEMENT{
   name="..."
   type="..."
   title="..."
   hint="..."
   mandatory="..."
   validate="..."
   condition="..."
   options="..."
   labels="..."
   value="..."
   buttonlabel="..."
   size="..."
   maxlength="..."
   rows="..."
   cols="..."
   format="..."
   titleformat="..."
   fieldformat="..."
   cssclass="..."
   focus="..."
   disabled="..."
   readonly="..."
   beforeclick=..."
   onFocus="..."
   onBlur="..."
   onMouseOver="..."
   onMouseOut="..."
   onSelect="..."
   onChange="..."
   onClick="..."
   onKeyUp="..."
}%
%ENDFORM%

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

Parameters

STARTFORM

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: view, viewauth, edit, save, create, rest, %SCRIPTURL{view}%/%WEB%/WebHome required - action="viewauth" restaction If action is rest: the rest function to call; see TWikiScripts. if action is rest - restaction="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 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). -   anchor="MyForm" method GET or POST (What's the difference?) - GET 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 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.

Attributes

Parameter Description Required Default value Example name Element name, must be unique. May contain spaces. The element name is used in the 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. - - %FORMELEMENT{   name="comment"   type="text"   title="Comment"   }% 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. - - %FORMELEMENT{   name="name"   type="textonly"   value="%WIKIUSERNAME%"   }% type="password" Creates a password textfield; otherwise same as text. - - %FORMELEMENT{   name="pw"   type="password"   }% type="upload" Creates an upload field; use with STARTFORM parameter action="upload" and set the name to "filepath". - - %STARTFORM{   name="uploadpicture"   action="upload"   topic="%WEB%.%TOPIC%"   method="post"   }%   %FORMELEMENT{   type="upload"   name="filepath"   title="Attach profile picture"   }%   ... type="textarea" Creates a textarea; use params rows and cols to set the size. - - %FORMELEMENT{   name="body"   type="textarea"   title="Message:"   rows="5"   cols="80"   }% 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. - - %FORMELEMENT{   name="friend"   type="select"   size="5"   title="Select friend:"   options="mary, peter, annabel, nicky, jennifer"   labels="Mary M, Peter P, Annabel A, Nicky N, Jennifer J"   }% 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. - - %FORMELEMENT{   name="friends"   type="selectmulti"   size="5"   title="Select friends:"   options="mary, peter, annabel, nicky, jennifer"   labels="Mary M, Peter P, Annabel A, Nicky N, Jennifer J"   value="mary,annabel"   }% 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. - - %FORMELEMENT{   name="friend"   type="dropdown"   title="Select friend:"   options="mary, peter, annabel, nicky, jennifer"   labels="Mary M, Peter P, Annabel A, Nicky N, Jennifer J"   value="peter"   }% type="checkbox" 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. - - %FORMELEMENT{   name="name"   type="checkbox"   title="Choose a name:"   options="mary=Mary M, peter=Peter P, annabel=Annabel A, nicky=Nicky N, jennifer=Jennifer J"   fieldformat="$e<br />"   value="mary,peter"   }% type="radio" 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. - - %FORMELEMENT{   name="name"   type="radio"   title="Choose a name:"   options="mary=Mary M, peter=Peter P, annabel=Annabel A, nicky=Nicky N, jennifer=Jennifer J"   fieldformat="$e<br />"   value="mary"   }% type="date" Creates a date button; requires DatePickerPlugin (installed by default). - - %FORMELEMENT{   name="date"   type="date"   dateformat="%e-%b-%y"   title="Select date:"   }% type="submit" Creates a submit button. - - %FORMELEMENT{   name="action"   type="submit"   buttonlabel="Send info"   }% type="hidden" Creates a hidden input field. - - %FORMELEMENT{   name="CarbonCopy"   type="hidden"   default="$Name earns $Salary"   }% 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" or 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: • 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. - - value="%WIKIUSERNAME%" or value="mary, peter, annabel" or value="Submit" buttonlabel The button label. - - buttonlabel="Submit" hint Input hint optionally displayed next to the form element. - - hint="Enter a TWiki.WikiWord" mandatory 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" format See Formatting below. %FORMELEMENT{   name="comment"   type="text"   title="Comment"   hint="anything"   mandatory="on"   format=" <b>$t</b> $m $h $e"   }% fieldformat See Formatting below. %FORMELEMENT{   name="friends"   type="radio"   options="mary=Mary M, peter=Peter P, annabel=Annabel A, nicky=Nicky N, jennifer=Jennifer J"   fieldformat="$e <br />"   }% titleformat See Formatting below. %FORMELEMENT{   name="comment"   type="text"   title="Comment"   titleformat=" <b>$t</b> <br />"   }% cssclass CSS class for the element - CSS classes: twikiInputField, twikiSubmit %FORMELEMENT{   name="Name"   type="text"   cssclass="twikiBroadcastMessage"   }% 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" focus focus="on" gives text entry focus to a field. Requires javascript. Only one element on the page can have focus. - - focus="on" 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 date formats for more info. - Default date format set in configure's Extensions section, DatePickerPlugin settings.

Javascript parameters

Note that all function calls should include (this).

Parameter Description Required Default value Example beforeclick (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.

• Status = %FORMSTATUS{"name_of_form"}%
  Possible values:
  • unchecked - the form has not been validated
  • error - the form has been validated and an error has been found
  • noerror - the form has been validated and no errors have been found
• unchecked status = %FORMSTATUS{"name_of_form" status="unchecked"}%
'1' in case of unchecked, otherwise '0'
• error status = %FORMSTATUS{"name_of_form" status="error"}%
'1' in case of error, otherwise '0'
• noerror status = %FORMSTATUS{"name_of_form" status="noerror"}%
'1' in case of noerror, otherwise '0'

FORMERROR

Retrieve the current validation errors - instead of displaying them just above the form.

• Errors = %FORMERROR{"name_of_form"}%

Retrieving form values

Use %URLPARAM{}% to display submitted form values. For example

   * Name = %URLPARAM{"MyName"}%
   * Names = %URLPARAM{"MyFriends" multiple="on" separator=", "}%

Formatting

Formatting of each form element can be set with the FORMELEMENT parameters:

• format - defines the display of:
  • title
  • field
  • hint
  • mandatory indicator
• fieldformat - 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 (<nop>) can be used to prevent expansion.

format

Attribute of STARTFORM or FORMELEMENT. The default format is:

$a
<p> $t <br /> $e $m $h </p>

This means that the title is displayed one line above the field, and the mandatory indicator and input hint are displayed at the right of the field.
To swith the order around use for example:

format="<p> $m $t $h <br />$e </p>"

elementformat

Attribute of STARTFORM. The default elementformat is simply

$e

This means that radio buttons and checkboxes are all displayed on one line. To put these items on one line each, write:

elementformat="$e <br />"

titleformat

Attribute of FORMELEMENT. The default titleformat is

 $t <br />

To display the title in bold, write:

titleformat=" *$t* <br />"

Date Formats

Attribute of FORMELEMENT when type="date" is used. Possible format specifiers:

%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 

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. Substitution of field references.
2. Validation

Substitution of field references

This allows to use entered field values as variables. For example:

• A form element has the name "To"
• Another form element (for instance a hidden field) has the default value "email response to $To"
• When the form is submitted, $To is substituted for the form element value with that name
• The form is passed along

An example form that uses substitution:

%STARTFORM{
name="mail"
action="view"
topic="%WEB%.%TOPIC%"
method="POST"
}%
%FORMELEMENT{
type="text"
name="To"
}%
%FORMELEMENT{
type="hidden"
name="Subject"
value="email to $To"
mandatory="on"
}%
%FORMELEMENT{
type="submit"
buttonlabel="Submit"
}%
%ENDFORM%

Subject is: %URLPARAM{"Subject"}%

Form validation

• Form elements can be checked on input that is nonempty, string, int, float or email
• If a validation error occurs, the form is displayed with error feedback

See FORMELEMENT:validate for usage instructions.
Use %FORMSTATUS{}% to retrieve the status of the form; see FORMSTATUS.

Examples

See Sandbox.FormPluginExamples

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %CACHECONTENTPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Lets you create simple and advanced web forms

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

Plugin Tests

• This plugin is enabled.

CSS classes

Class name Note 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)

Installation

Attention: This plugin version depends on the new TWiki:Plugins.DatePickerPlugin; the JSCalendarContrib is no longer needed by this plugin and must be upgraded or uninstalled.

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. Copyright: © 2007-2010 Arthur Clemens, Sven Dowideit, Eugen Mayer; © 2005-2015 TWiki:TWiki.TWikiContributor License: GPL (GNU General Public License) Plugin Version: 2015-02-25

CPAN Dependencies: - Other Dependencies: - Perl Version: 5.005 Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/FormPlugin Feedback: http://TWiki.org/cgi-bin/view/Plugins/FormPluginDev Appraisal: http://TWiki.org/cgi-bin/view/Plugins/FormPluginAppraisal

Related Topics: TWikiPreferences, TWikiPreferences, Plugins