CGI-QuickForm
view release on metacpan or search on metacpan
=head1 NAME
CGI::QuickForm - Perl module to provide quick CGI forms.
=head1 SYNOPSIS
# Minimal example. (Insecure no error checking.)
#!/usr/bin/perl -w
use strict ;
use CGI qw( :standard :html3 ) ;
use CGI::QuickForm ;
show_form(
-ACCEPT => \&on_valid_form, # You must supply this subroutine.
-TITLE => 'Test Form',
-FIELDS => [
{ -LABEL => 'Name', }, # Default field type is textfield.
{ -LABEL => 'Age', }, # Stored in param( 'Age' ).
],
) ;
sub on_valid_form {
my $name = param( 'Name' ) ;
my $age = param( 'Age' ) ;
open PEOPLE, ">>people.tab" ;
print PEOPLE "$name\t$age\n" ;
close PEOPLE ;
print header, start_html( 'Test Form Acceptance' ),
h3( 'Test Form Data Accepted' ),
p( "Thank you $name for your data." ), end_html ;
}
# All QuickForm options (aide memoir)
#!/usr/bin/perl -w
use strict ;
use CGI qw( :standard :html3 ) ;
use CGI::QuickForm ;
show_form(
-ACCEPT => \&on_valid_form,
-BORDER => 0,
-FOOTER => undef,
-HEADER => undef,
-INTRO => undef,
-LANGUAGE => 'en',
-USER_REQUIRED => undef,
-USER_INVALID => undef,
-TITLE => 'Test Form',
-REQUIRED_HTML => '<span style="font-weight:bold;color:BLUE">+</span>',
-INVALID_HTML => '<span style="font-weight:bold;color:RED">*</span>',
-VALIDATE => undef, # Set this to validate the entire record
-SIZE => undef,
-MAXLENGTH => undef,
-ROWS => undef,
-COLUMNS => undef,
-CHECK => 1,
-SPACE => 0, # Output some newlines to assist debugging if 1
-MULTI_COLUMN => 0,
-NAME => undef,
-ONSUBMIT => undef,
-JSCRIPT => {},
-STYLE_FIELDNAME => '',
-STYLE_FIELDVALUE => '',
-STYLE_BUTTONS => '',
-STYLE_ROW => '',
-STYLE_WHY => '',
-TABLE_OPTIONS => '',
-FIELDS => [
{
-LABEL => 'Personal Details',
-HEADLINE => 1,
-STYLE_FIELDNAME => '',
-COLSPAN => 2,
-END_ROW => 1,
},
{
-LABEL => 'Name',
-START_ROW => 1,
-END_ROW => 1,
-COLSPAN => 1,
-REQUIRED => undef,
-TYPE => 'textfield',
-VALIDATE => undef, # Set this to validate the field
-CLEAN => undef, # Set this to clean up valid data
-DESC => undef,
-STYLE_FIELDNAME => '', # If set over-rides form-level setting
-STYLE_FIELDVALUE => '', # If set over-rides form-level setting
-STYLE_ROW => '', # If set over-rides form-level setting
# Lowercase options are those supplied by CGI.pm
-name => undef, # Defaults to -LABEL's value.
-default => undef,
-size => 30,
-maxlength => undef,
},
# For all others: same QuickForm options as above
# and all CGI.pm options (which vary with -TYPE) available
{
-LABEL => 'Address',
-TYPE => 'textarea',
-rows => 3,
-columns => 40,
},
{
-LABEL => 'Password',
-TYPE => 'password_field',
},
{
-LABEL => 'Hair colour',
-TYPE => 'scrolling_list',
'-values' => [ qw( Red Black Brown Grey White ) ],
Optional string. This is used to present any text following the form and if
used it must include everything up to and including final "</html>", e.g.:
my $footer = p( "Thank's for your efforts." ) .
h6( "Copyright (c) 1999 Summer plc" ) . end_html ;
show_form(
-FOOTER => $footer,
# etc.
Alternatively, supply a code reference, e.g.:
sub my_footer {
print '<hr>The end' . end_html ;
}
show_form(
-FOOTER => \&my_footer,
# etc.
Note that the code that's called is responsible for printing its own output.
=item C<-HEADER>
Optional string. This is used to present your own title and text before the
form proper. If you use this it must include everything from
"Content-type: text/html" onwards. For example:
my $header = header . start_html( "This is my Title" ) .
h2( "My new Form" ) . p( "Please answer the questions!" ) ;
show_form(
-HEADER => $header,
# etc
Alternatively, supply a code reference, e.g.:
sub my_header {
print header . start_html( 'A new beginning' ) ;
}
show_form(
-HEADER => \&my_header,
# etc.
Note that the code that's called is responsible for printing its own output.
See C<example5>.
=item C<-INTRO>
Optional string. If you specify C<-TITLE> you may want to specify this field
too; it puts a paragraph of text before the form. The English default is
"Please enter the information.", there is a default for each supported
language (see C<-LANGUAGE>).
=item C<-INVALID_HTML>
Optional HTML string. Default is:
<span style="font-weight:bold;color:RED">*</span>
You can over-ride this to set your own marker to indicate an invalid field.
You could use an image tag for example:
<img src="/images/invalid.jpg" alt="*" />
Note that if you use your own C<-USER_REQUIRED> or C<-USER_INVALID> strings,
this string will replace the sequence C<~I~> if it occurs.
See C<example1> and the companion option C<-REQUIRED_HTML>.
=item C<-JSCRIPT>
Optional hash reference; should contain at least one element 'src' which
should contain some Javascript, e.g.
-JSCRIPT => { src => 'document.Address.myfield.focus()' },
This is just a wrapper for CGI.pm's C<-script> option. (See C<-NAME> and
C<-ONSUBMIT>.)
=item C<-LANGUAGE>
Optional string. This option accepts 'en' (English), 'cy' (Welsh), 'de'
(German), 'es' (Spanish), 'fr' (French) and 'he' (Hebrew) - the French
translation was done by Babelfish - see CHANGES for the human
translators. ('english' is also supported for backward compatibility.)
If people provide me with translations I will add other languages.
This is used for the presentation of messages to the user, e.g.:
Please enter the information.
Fields marked with + are required.
Fields marked with * contain errors or are empty.
If you want to create your own 'required' or 'invalid' strings using the
C<-USER_REQUIRED> and/or C<-USER_INVALID> options and set C<-LANGUAGE>
to 'user'. If you want your own 'intro' string set it with C<-INTRO>.
If you're using hebrew, 'he', you will need to define your own header,
that specifies an appropriate character set, language and writing
direction. For example:
my $header = header( -charset => 'windows-1255' ) .
start_html( -lang => 'hebrew', -title => 'My Title' ) .
qq{<div dir="RTL">} .
h2( 'My Title' );
show_form(
-HEADER => $header,
-LANGUAGE => 'he',
# etc.
See C<example1>.
=item C<-MULTI_COLUMN>
Optional boolean (default false). If false QuickForm behaves as it always has
producing a two column table, the first column with field names and the second
column with field values. If true QuickForm will put all field names and field
values in the same row, except where you force a new row to be used by marking
some fields with C<-END_ROW => 1,>. See the field-level options C<-START_ROW>,
C<-END_ROW> and C<-COLSPAN>. See C<example2> and C<example4> which have been
updated to demonstrate these options.
=item C<-NAME>
Optional string. If specified this string is given to the start_form()
function as its C<-name> option; used for identifying the form for Javascript.
(See C<-JSCRIPT> and C<-ONSUBMIT>.)
=item C<-ONSUBMIT>
Optional string. If specified this string is given to the start_form()
function as its C<-onSubmit> option; used with Javascript.
(See C<-JSCRIPT> and C<-NAME>.)
=item C<-REQUIRED_HTML>
Optional HTML string. Default is:
<span style="font-weight:bold;color:BLUE">+</span>
You can over-ride this to set your own marker to indicate a required field.
Note that if you use your own C<-USER_REQUIRED> or C<-USER_INVALID> strings,
this string will replace the sequence C<~R~> if it occurs.
See C<example1> and the companion option C<-INVALID_HTML>.
=item C<-TITLE>
Required string (unless you use C<-HEADER>). This is used as the form's title
and as a header on the form's page - unless you use the C<-HEADER> option (see
above) in which case this option is ignored.
=item C<-USER_INVALID>
Optional string. If specified you I<must> set C<-LANGUAGE> to 'user' and if
you are not writing English then you'll need to set C<-USER_REQUIRED> too.
This string is used as the error text for invalid fields. If it contains the
character sequence C<~I~> that sequence will be replaced with the HTML used to
signify an invalid field (which you can override by setting C<-INVALID_HTML>).
=item C<-USER_REQUIRED>
Optional string. If specified you I<must> set C<-LANGUAGE> to 'user' and if
you are not writing English then you'll need to set C<-USER_INVALID> too.
This string is used as the error text for required fields. If it contains the
character sequence C<~R~> that sequence will be replaced with the HTML used to
signify a required field (which you can override by setting
C<-REQUIRED_HTML>).
=item C<-VALIDATE>
Optional subroutine reference. This routine is called after each individual
field has been validated. It is given the fields in a name=>value hash. It
should either return a simple true (valid) or false (invalid) or a two element
list, the first element being a true/false value and the second value either
an empty string or an (html) string which gives the reason why the record is
invalid. Typically it may have this structure:
sub valid_record {
my %field = @_ ;
my $valid = 1 ;
# Do some multi-field validation, e.g.
if( $field{'colour'} eq 'blue' and
$field{'make'} eq 'estate' ) {
$valid = 0 ; # No blue estates available.
}
# etc.
$valid ; # Return the valid variable which may now be false.
}
or now (preferred style):
sub valid_record {
my %field = @_ ;
my $valid = 1 ;
my $why = '' ;
one. The fields are displayed in the order given. The options available in
each field hash are covered in the next section.
=back
=head2 QuickForm field-level options
=over
=item C<-CLEAN>
Optional subroutine reference. If specified this subroutines will be called
for the relevant field if and only if the whole record is valid, i.e. just
before calling your C<on_valid_form> subroutine. It will receive a single
parameter (the value of the relevant param), and must return a new value. A
typical routine might clean up excess whitespace, e.g.:
sub cleanup {
local $_ = shift ; # This is the value of param( <fieldname> )
tr/\t \n\r\f/ /s ; # Convert multiple whitespace to one space.
s/^\s*//o ; # Remove leading whitespace.
s/\s*$//o ; # Remove trailing whitespace.
$_ ;
}
=item C<-COLSPAN>
Optional integer. Default is 1; ignored if C<-MULTI_COLUMN> is false. If you
choose C<-MULTI_COLUMN> and want some fields to span multiple rows then you
can use this option to define how many rows are spanned. (Note that every
field is two rows wide, one for the fieldname and one for the fieldvalue.)
=item C<-DESC>
Optional string. This is a short piece of descriptive text which appears above
the field and is used to give the user a little guidance on what they should
choose or enter. Normally if you use these then you would set the form-level
C<-BORDER> option to 1 to help visually group the field and its descriptive
text.
=item C<-HEADLINE>
Optional boolean. Default is false. If set to true then instead of inserting a
field, QuickForm will insert a label. This is used to separate blocks of input
fields - see C<example2>. If this is true then you will probably want to set
C<-STYLE_FIELDNAME>, e.g. to make the text stand out; and also C<-COLSPAN> to
the number of columns in the form if using C<-MULTI_COLUMN>. The C<-LABEL> is
the text that will be displayed. If using C<-MULTI_COLUMN> any field that
preceeds C<-HEADLINE> should normally set C<-END_ROW> to true; this isn't done
automatically in case your form has two or more columns and you want to have
different headlines above each column. Thus a typical headline field looks
like:
{
-LABEL => 'General Information',
-HEADLINE => 1,
-COLSPAN => 2, # Probably needs to be more for -MULTI_COLUMN
-END_ROW => 1,
-STYLE_FIELDNAME => 'style="background-color:black;color:white;font-weight:bold"',
},
=item C<-LABEL>
Required string. This is the display label for the field. It is also used as
the field's name if no C<-name> option is used.
=item C<-REQUIRED>
Optional boolean. Default is false. If set to true the field must contain
something. Should only be used with text fields. It is ignored if C<-VALIDATE>
is given since C<-VALIDATE> overrides (see later).
=item C<-START_ROW> and C<-END_ROW>
Optional booleans, default is true. These options are only relevant if the
form-level C<-MULTI_COLUMN> option is set to true in which case these options
are used to identify at which fields rows start and end. In practice
C<-START_ROW> should never be needed; simply set C<-END_ROW => 1,> in each
field which is to be the last field in a given row. Note that because some
fields may need to span several columns e.g. a layout where say the first two
fields are side-by-side and the following field is so wide it must take the
whole width; the wider field's C<-COLSPAN> setting may need to be set to
C<-COLSPAN => 3,> or similar. See C<example2> and C<example4> which have been
updated to demonstrate these options.
=item C<-STYLE_*>
Some of these options may be applied on a per-field basis; they are documented
under Styles later.
=item C<-TYPE>
Optional string. Default is C<textfield>. May be any field supported by
C<CGI.pm>.
=item C<-VALIDATE>
Optional subroutine reference. If specified this subroutine will be called
when the user presses the submit button; its argument will be the value of the
field. It should either return a simple true (valid) or false (invalid) or a
two element list, the first element being a true/false value and the second
value either an empty string or an (html) string which gives the reason why
the field is invalid. Its typical structure may be:
sub valid_national_insurance {
my $ni = shift ;
$ni = uc $ni ;
( $ni =~ /^[A-Z]{2}\d{7}[A-Z]$/o ) ? 1 : 0 ;
}
or now (preferred style):
sub valid_national_insurance {
my $ni = shift ;
my $why = '<i>Should be 2 letters followed by 7 ' .
'digits then a letter</i>' ;
( run in 1.111 second using v1.01-cache-2.11-cpan-39bf76dae61 )