Why not adopt me?
NAME
CGI::QuickForm - Perl module to provide quick CGI forms.
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 "$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
#!/usr/bin/perl -w
use strict ;
use CGI qw( :standard :html3 ) ;
use CGI::QuickForm ;
show_form(
-ACCEPT => \&on_valid_form,
-FOOTER => undef,
-HEADER => undef,
-LANGUAGE => 'en',
-TITLE => 'Test Form',
-VALIDATE => undef, # Set this to validate the entire record
-SIZE => undef,
-MAXLENGTH => undef,
-ROWS => undef,
-COLUMNS => undef,
-FIELDS => [
{
-LABEL => 'Name',
-REQUIRED => undef,
-TYPE => 'textfield',
-VALIDATE => undef, # Set this to validate the field
-CLEAN => undef, # Set this to clean up valid data
# Lowercase options are those supplied by CGI.pm
-name => undef, # Defaults to -LABEL's value.
-default => undef,
-size => 30,
-maxlength => undef,
},
{
-LABEL => 'Address',
-REQUIRED => undef,
-TYPE => 'textarea',
-VALIDATE => undef,
-CLEAN => undef,
-name => undef,
-default => undef,
-rows => 3,
-columns => 40,
},
{
-LABEL => 'Password',
-REQUIRED => undef,
-TYPE => 'password_field',
-VALIDATE => undef,
-CLEAN => undef,
-name => undef,
-value => undef,
-size => 10,
-maxlength => undef,
},
{
-LABEL => 'Hair colour',
-REQUIRED => undef,
-TYPE => 'scrolling_list',
-VALIDATE => undef,
-CLEAN => undef,
-name => undef,
-values => [ qw( Red Black Brown Grey White ) ],
-size => 1,
-multiples => undef,
},
{
-LABEL => 'Worst Sport',
-REQUIRED => undef,
-TYPE => 'radio_group',
-VALIDATE => undef,
-CLEAN => undef,
-name => undef,
-values => [ qw( Boxing Cricket Golf ) ],
-default => 'Golf',
-size => undef,
-multiples => undef,
},
# Any other CGI.pm field can be used in the same way.
],
-BUTTONS => [
{ -name => 'Add' },
{ -name => 'Edit' },
{ -name => 'List' },
{ -name => 'Remove' },
],
) ;DESCRIPTION
show_form, provides a quick and simple mechanism for providing on-line CGI forms.
When show_form executes it presents the form with the fields requested. As you can see from the minimal example at the beginning of the synopsis it will default everything it possibly can to get you up and running as quickly as possible.
If you have specified any validation it will validate when the user presses the submit button. If there is an error it will re-present the form with the erroneous fields marked and with all the data entered in tact. This is repeated as often as needed. Once the user has corrected all errors and the data is valid then your &on_valid_form subroutine will be called so that you can process the valid data in any way you wish.
QuickForm form-level (record-level) options
-ACCEPT Required subroutine reference. This is a reference to the subroutine to execute when the form is successfully completed, i.e. once all the fields and the whole record are valid (either because no validation was requested or because every validation subroutine called returned true). The parameters are accessible via CGI.pm, so your &on_valid_form may look something like this:
sub on_valid_form {
my $first_param = param( 'first' ) ;
my $second_param = param( 'second' ) ;
my $third_param = param( 'third' ) ;
# Process, e.g. send an email or write a record to a file or database.
# Give the user a thank you.
}-BUTTONS Optional array reference. This is an array of submit buttons. The buttons appear at the bottom of the form, after all the fields. Each button is defined as an anonymous hash, e.g.
-BUTTONS => [
{ -name => 'New' },
{ -name => 'Update' },
],although any other legitimate CGI.pm options may also be given, e.g.
-BUTTONS => [
{ -name => 'New', -value => 'BUTTON_NEW' },
{ -name => 'Update' -value => 'BUTTON_UPDATE' },
],If no -BUTTONS option array reference is given it will be created with { -name =< 'Submit' } by default. Note that this option replaces the -BUTTONLABEL option. If -BUTTONLABEL is used it will be converted into the new form automatically so old scripts will not be broken. However use of -BUTTONS is recommended for all new work.
-FOOTER 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-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-LANGUAGE Optional string. This option accepts 'en' (english), 'de' (german) and 'fr' (french) - the translations were done by Babelfish. ('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.-TITLE Required string (unless you use -HEADER). This is used as the form's title and as a header on the form's page - unless you use the -HEADER option (see above) in which case this option is ignored.
-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 and must return true if the record as a whole is valid, false otherwise. 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.
}-COLUMNS Optional integer. If set then any -TYPE => textarea will have a -columns set to this value unless an explicit -columns is given.
-MAXLENGTH Optional integer. If set then any -TYPE => textfield will have a -maxlength set to this value unless an explicit -maxlength is given.
-ROWS Optional integer. If set then any -TYPE => textarea will have a -rows set to this value unless an explicit -rows is given.
-SIZE Optional integer. If set then any -TYPE => textfield will have a -size set to this value unless an explicit -size is given. For example:
show_form(
-ACCEPT => \&on_valid_form, # You must supply this subroutine.
-TITLE => 'Test Form',
-SIZE => 50,
-FIELDS => [
{ -LABEL => 'Name', },
{ -LABEL => 'Age', },
],
) ;
# Both the fields will be textfields because that is the default and both
# will have a -size of 50.
show_form(
-ACCEPT => \&on_valid_form, # You must supply this subroutine.
-TITLE => 'Test Form',
-SIZE => 50,
-MAXLENGTH => 70,
-FIELDS => [
{
-LABEL => 'Name',
-CLEAN => \&cleanup, # You must supply this (see later).
},
{ -LABEL => 'Age', },
{
-LABEL => 'Country',
# Here we upper case the country.
-CLEAN => sub { local $_ = shift ; tr/a-z/A-Z/ ; $_ },
-size => 20,
},
],
) ;
# All three fields will be textfields. Name and Age will have a -size of
# 50 but Country will have a -size of 20. All three will have a -maxlength
# of 70.-FIELDS Required array reference. This is an array of hashes; there must be at least one. The fields are displayed in the order given. The options available in each field hash are covered in the next section.
QuickForm field-level options
-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 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.
$_ ;
}-LABEL Required string. This is the display label for the field. It is also used as the field's name if no -name option is used.
-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 -VALIDATE is given since -VALIDATE overrides (see later).
-TYPE Optional string. Default is textfield. May be any field supported by CGI.pm.
-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 must return true if the field is valid false otherwise. 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 ;
}CGI.pm field-level options
All the other options passed in the hash should be the lowercase options supported by CGI.pm for the particular field type. For example for a -TYPE of textfield the options currently supported are -name, -default, -size and -maxlength; you may use any, all or none of them since CGI.pm always provides sensible defaults. See "All QuickForm options" in the SYNOPSIS above for examples of the most common field types.
EXAMPLE #1: Using a form to generate email
This program is provided as an example of QuickForm's capabilities, it is not a production-quality program: it has no error checking and is not secure.
#!/usr/bin/perl -w
use strict ;
use CGI qw( :standard :html3 ) ;
use CGI::QuickForm ;
show_form(
-TITLE => 'Test Form',
-ACCEPT => \&on_valid_form,
-FIELDS => [
{
-LABEL => 'Forename',
-REQUIRED => 1,
},
{
-LABEL => 'Surname',
-REQUIRED => 1,
},
{ -LABEL => 'Age', },
{
-LABEL => 'Sex',
-TYPE => 'radio_group',
'-values' => [ qw( Female Male ) ],
},
],
) ;
# This subroutine will only be called if the name fields contain at
# least one character.
sub on_valid_form {
my $forename = param( 'Forename' ) ;
my $surname = param( 'Surname' ) ;
my $age = param( 'Age' ) ;
open MAIL, "|/usr/lib/sendmail -t" ;
print MAIL "From: test\@localhost\n" .
"To: user\@localhost\n" .
"Subject: Quick Form Email Test\n\n" .
"Name: $forename $surname\n" .
"Age: $age\n" ;
print header, start_html( 'Test Form Data Accepted' ),
h3( 'Test Form Data Accepted' ),
p( "Thank you $forename for your data." ), end_html ;
}EXAMPLE #2: Appending data to a file
This program is provided as an example of QuickForm's capabilities, it is not a production-quality program: it has no error checking and is not secure.
#!/usr/bin/perl -w
use strict ;
use CGI qw( :standard :html3 ) ;
use CGI::QuickForm ;
show_form(
-TITLE => 'Test Form',
-ACCEPT => \&on_valid_form,
-VALIDATE => \&valid_form,
-SIZE => 40,
-MAXLENGTH => 60,
-FIELDS => [
{
-LABEL => 'Forename',
-VALIDATE => \&valid_name,
-CLEAN => \&cleanup, # (See earlier for definition.)
},
{
-LABEL => 'Surname',
-VALIDATE => \&valid_name,
-CLEAN => \&cleanup, # (See earlier for definition.)
},
{
-LABEL => 'Age',
# &mk_valid_number generates a subroutine (a closure) and
# returns a reference to that subroutine.
-VALIDATE => &mk_valid_number( 3, 130 ),
-size => 10,
-maxlength => 3,
},
],
) ;
# This will only be called if all the validation routines return true.
sub on_valid_form {
my $forename = param( 'Forename' ) ;
my $surname = param( 'Surname' ) ;
my $age = param( 'Age' ) ;
open FILE, ">>namedata.tab" ;
print FILE "$surname\t$forename\t$age\n" ;
close FILE ;
print header, start_html( 'Test Form Data Accepted' ),
h3( 'Test Form Data Accepted' ),
p( "Thank you $forename for your data." ), end_html ;
}
# This is called to validate the entire form (record).
# Use a routine like this if there are relationships between fields that
# must be tested.
sub valid_form {
my %rec = @_ ;
my $valid = 1 ;
# We don't allow (perfectly valid!) names like 'John John'.
$valid = 0 if lc $surname eq lc $forename ;
$valid ;
}
sub valid_name {
my $name = shift ;
my $valid = 1 ;
$valid = 0 if $name !~ /^\w{2,}$/o ;
$valid ;
}
sub mk_valid_number {
my( $min, $max ) = @_ ;
sub { $min <= $_[0] and $_[0] <= $max } ;
}BUGS
None that have come to light (yet).
AUTHOR
Mark Summerfield. I can be contacted as <summer@chest.ac.uk> - please include the word 'quickform' in the subject line.
COPYRIGHT
Copyright (c) Mark Summerfield 1999. All Rights Reserved.
This module may be used/distributed/modified under the LGPL.