This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.
File: pm.info, Node: CGI/EncryptForm, Next: CGI/Enurl, Prev: CGI/Debug, Up: Module List
Implement trusted stateful CGI Form Data using cryptography.
************************************************************
NAME
====
CGI::EncryptForm - Implement trusted stateful CGI Form Data using
cryptography.
SYNOPSIS
========
use CGI::EncryptForm;
my $cfo = new CGI::EncryptForm(secret_key => 'my secret');
my $hashref = { username => 'joe', password => 'test' };
my $encrypted_string = $cfo->encrypt($hashref);
if (!defined($encrypted_string)) {
print $cfo->error();
return;
}
my $newhashref = $cfo->decrypt($encrypted_string);
if (!defined($newhashref)) {
print $cfo->error();
return;
}
print $newhashref->{'username'};
PREREQUISITES
=============
This modules requires the following perl modules:
Digest::SHA1, Crypt::HCE_SHA and Storable
ABSTRACT
========
Many CGI programmers take for granted the validity of stateful CGI form
data.
Im talking about the common scenario where you present a form to the
browser, the user fills in the form, you verify the form values, store
them in the next form as hidden fields, the user fills in another form,
the script appends these results to the next form in hidden fields and so
on.
Using hidden form fields is one mechanism where by CGI scripts can
maintain state in the process of collecting information from the user.
Unfortunately, it is also one of the weakest to implement because the
CGI script must trust the hidden form fields and there values, provided by
the users browser. At some point in time the CGI program does something
with this stateful information. To be completely sure the hidden fields
haven't been altered along the way and thus rendered initial verification
checks useless, the programmer must continually verify all new form fields
and previous state (encapsulated in hidden form fields) to be sure the
desired constraints are met. This process of verification becomes tedious
to program especially if there are many forms required to produce a final
result.
To tackle this problem I created CGI::EncryptForm, where by instead of
including state in hidden form fields verbatim, we use SHA1 encryption
algorithm to provide a satisfactory level of trust between the users
browser and the CGI script.
DESCRIPTION
===========
An object is created with a secret key defined by the CGI script. The
objects encrypt() method is called with a perl data structure, which in the
context of CGI scripts would normally contain key/value pairs. The
encrypt() method returns an encrypted string. The encrypted string is
stored in a hidden form field. The user fills in the form. The CGI script
processes the form, extracts the encrypted string from the hidden form
field, decrypts the string and returns the original data structure.
Further results from the form are added to the data structure, then it is
encrypted again and stored in the next form as a hidden field. This
process continues until the CGI script has all the desired information and
is ready to process it. To process the results, the CGI script decrypts
the encrypted string from the last hidden form field, which contains the
*collective state* of all previous form input.
Along the way, the users input was verified only once. The fact that
state was encrypted and therefore trusted, renders the process of
continually verifying all state for each form processed, unnecessary.
METHODS
=======
*new CGI::EncryptForm*([secret_key => $s [, usecharset => $a]])
Create a new CGI::EncryptForm object. All of the paramaters are
optional. $s specifies the secret key to use during
encryption/decryption. $a specifies whether to enable (1) or disable
(0) the character set encoding/decoding of the encrypted/decrypted
result. By default this is enabled.
encrypt($hashref)
Encrypt the data structure and return an encrypted string. $hashref
must be a reference to an associative array supported by the Storable
module. If called with no arguement, returns the previous encrypted
string.
Upon error, the method returns undef and sets error().
decrypt($encrypted_string)
Decrypt the encrypted string and return a reference to an associative
array. $encrypted_string must be a scalar previously generated by
encrypt(). If called with no arguement, returns the previous
reference.
Upon error, the method returns undef and sets error(). If the
encrypted string is tampered with the decryption routine should fail
with undef, but this is ultimately dependant on the strength of SHA1
digests.
*secret_key*($secret)
Sets the secret key for use during encryption/decryption. This method
is analogues to the secret_key paramater when creating a
CGI::EncryptForm object. If called with no $secret it returns the
current secret key or undef if undefined.
Upon error, the method returns undef and sets error().
*usecharset*(1)
Enables or disables the character set encoding/decoding of
encrypted/decrypted strings. This method is analogues to the
usecharset paramater when creating a CGI::EncryptForm object. By
default usecharset is enabled (1) and should be ignored unless you
use this module in non CGI programs. The encode/decode routine
applies the default or user defined (*see charset()*) character set to
encode/decode the encrypted string, before returning to the caller.
charset($arrayref)
Sets the character set which will be used to encode/decode the
encrypted/decrypted string. This method accepts a single array
reference that must contain a character set from 0 to 255, where by
each element must be 2 characters and UNIQUE. e.g.
charset(qw[/aA aB aC aD ... /])
If this method is not called with your own character set, a default
character set will be used which produces suitable output to store the
result of the encrypt() method in form fields, URL's and cookies.
Upon error, the method returns undef and sets error().
error()
Returns the last error as a scalar. You would normally read this if
any method returns undef. error() is always cleared for each method
that executes successfully.
EXAMPLE
=======
This example illustrates the use of CGI::EncryptForm in combination with
CGI.pm to maintain stateful information in a multi-form CGI script.
#!/usr/local/bin/perl
use CGI::EncryptForm;
use CGI;
use vars qw($cgi $cfo);
$cgi = new CGI();
$cfo = new CGI::EncryptForm(secret_key => 'blah');
print $cgi->header(), $cgi->start_html(), $cgi->start_form();
if (defined $cgi->param('enc')) {
form3();
}
elsif (defined $cgi->param('something')) {
form2();
}
else {
form1();
}
print $cgi->end_html(), $cgi->end_form();
sub form1 {
print "
form1
",
"Type something and we will remember it: ",
$cgi->textfield('something'), $cgi->submit();
}
sub form2 {
print "
form2
",
$cgi->hidden(-name=>'enc', value=>$cfo->encrypt({ $cgi->Vars })),
"Now click here and I will tell you what you typed based on ",
"the encrypted hidden form field, which you would normally ",
"only see if you view the HTML source. For the sake of this ",
"demonstration the encrypted field is included below.
",
$cfo->encrypt(), "
",
"Before proceeding with this form I suggest you take note of ",
"what the encrypted field looks like, then click the back ",
"button and resubmit the previous form with the same value ",
"again. What you will notice is the encrypted field will ",
"change. This is because the SHA encryption algorithm is ",
"based on a secret key and a random key. In the module we ",
"take care of generating a unique random key for each ",
"invocation of the encryption routine, which is why a ",
"distinct encrypted string is produced each time.",
"
", $cgi->submit();
}
sub form3 {
my $hashref = $cfo->decrypt($cgi->param('enc'));
if (!defined($hashref)) {
print $cfo->error();
return;
}
print "
Now we can start coding...
## START ##
use CGI::FastTemplate;
my $tpl = new CGI::FastTemplate("/path/to/template/files");
$tpl->define( main => "main.tpl",
table => "table.tpl",
row => "row.tpl",
);
$tpl->assign(TITLE => "FastTemplate Test");
for $n (1..3)
{
$tpl->assign( NUMBER => $n,
BIG_NUMBER => $n*10);
$tpl->parse(ROWS => ".row");
}
$tpl->parse(MAIN => ["table", "main"]);
$tpl->print();
## END ##
When run it returns:
FastTemplate Test
1
10
2
20
3
30
If you're thinking you could have done the same thing in a few lines of
plain perl, well yes you probably could. But, how would a graphic
designer tweak the resulting HTML? How would you have a designer editing
the HTML while you're editing another part of the code? How would you
save the output to a file, or pipe it to another application (e.g.
sendmail)? How would you make your application multi-lingual? How would
you build an application that has options for high graphics, or text-only?
FastTemplate really starts to shine when you are building mid to large
scale web applications, simply because it begins to separate the
application's generic logic from the specific implementation.
COPYRIGHT
=========
Copyright (c) 1998-99 Jason Moore . All rights
reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
Artistic License for more details.
AUTHOR
======
Jason Moore
SEE ALSO
========
mod_perl(1).
File: pm.info, Node: CGI/Form, Next: CGI/FormMagick, Prev: CGI/FastTemplate, Up: Module List
Build Smart HTML Forms on Top of the CGI:: Modules
**************************************************
NAME
====
CGI::Form - Build Smart HTML Forms on Top of the CGI:: Modules
ABSTRACT
========
This perl library uses perl5 objects to make it easy to create Web
fill-out forms and parse their contents. This package defines CGI
objects, entities that contain the values of the current query string and
other state variables. Using a CGI object's methods, you can examine
keywords and parameters passed to your script, and create forms whose
initial values are taken from the current query (thereby preserving state
information).
INSTALLATION:
=============
To use this package, install it in your perl library path (usually
/usr/local/lib/perl5/ and add the following to your perl CGI script:
Use CGI::Form;
DESCRIPTION
===========
CREATING A NEW FORM OBJECT AND PROCESSING PARAMETERS:
-----------------------------------------------------
$query = new CGI::Form;
This will parse the input (from both POST and GET methods) and store it
into a perl5 object called $query. This method is inherited from *Note
CGI/Request: CGI/Request,. See its manpage for details. Similarly,
CGI::Form uses CGI::Request to get and set named query parameters, e.g.
@values = $query->param('foo');
-and-
$query->param('foo','an','array','of','values');
or whatever!
CALLING CGI::Form FUNCTIONS THAT TAKE MULTIPLE ARGUMENTS
--------------------------------------------------------
In versions of Form.pm prior to 2.8, it could get difficult to remember
the proper order of arguments in CGI function calls that accepted five or
six different arguments. As of 2.8, there's a better way to pass
arguments to the various CGI functions. In this style, you pass a series
of name=>argument pairs, like this:
$field = $query->radio_group(-name=>'OS',
-values=>[Unix,Windows,Macintosh],
-default=>'Unix');
The advantages of this style are that you don't have to remember the
exact order of the arguments, and if you leave out a parameter, in most
cases it will default to some reasonable value. If you provide a
parameter that the method doesn't recognize, it will usually do something
useful with it, such as incorporating it into the HTML form tag. For
example if Netscape decides next week to add a new JUSTIFICATION parameter
to the text field tags, you can start using the feature without waiting
for a new version of CGI.pm:
$field = $query->textfield(-name=>'State',
-default=>'gaseous',
-justification=>'RIGHT');
This will result in an HTML tag that looks like this:
Parameter names are case insensitive: you can use -name, or -Name or
-NAME. You don't have to use the hyphen if you don't want to. After
creating a CGI object, call the *use_named_parameters()* method with a
nonzero value. This will tell CGI.pm that you intend to use named
parameters exclusively:
$query = new CGI;
$query->use_named_parameters(1);
$field = $query->radio_group('name'=>'OS',
'values'=>['Unix','Windows','Macintosh'],
'default'=>'Unix');
Actually, CGI.pm only looks for a hyphen in the first parameter. So
you can leave it off subsequent parameters if you like. Something to be
wary of is the potential that a string constant like "values" will collide
with a keyword (and in fact it does!) While Perl usually figures out when
you're referring to a function and when you're referring to a string, you
probably should put quotation marks around all string constants just to
play it safe.
CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:
-----------------------------------------------------------------
$myself = $query->self_url
print "I'm talking to myself.
self_url() will return a URL, that, when selected, will reinvoke this
script with all its state information intact. This is most useful when
you want to jump around within the document using internal anchors but you
don't want to disrupt the current contents of the form(s). Something like
this will do the trick.
$myself = $query->self_url
print "See table 1
print "See table 2
print "See for yourself
This method is actually defined in *Note CGI/Base: CGI/Base,, but is
passed through here for compatability with CGI.pm
CREATING THE HTTP HEADER:
-------------------------
print $query->header;
-or-
print $query->header('image/gif');
header() returns the Content-type: header. you can provide your own
MIME type if you choose, otherwise it defaults to text/html.
This method is provided for compatability with CGI.pm *only*. It is
much better to use the SendHeaders() method of *Note CGI/Base: CGI/Base,.
NOTE: This is a temporary method that will be replaced by the
CGI::Response module as soon as it is released.
GENERATING A REDIRECTION INSTRUCTION
------------------------------------
print $query->redirect('http://somewhere.else/in/movie/land');
redirect the browser elsewhere. If you use redirection like this, you
should not print out a header as well.
This method is provided for compatability with CGI.pm *only*. New
scripts should use CGI::Base's redirect() method instead.
CREATING THE HTML HEADER:
-------------------------
print $query->start_html(-title=>'Secrets of the Pyramids',
-author=>'fred@capricorn.org',
-base=>'true',
-BGCOLOR=>"#00A0A0"');
-or-
print $query->start_html('Secrets of the Pyramids',
'fred@capricorn.org','true',
'BGCOLOR="#00A0A0"');
This will return a canned HTML header and the opening tag. All
parameters are optional. In the named parameter form, recognized
parameters are -title, -author and -base (see below for the explanation).
Any additional parameters you provide, such as the Netscape unofficial
BGCOLOR attribute, are added to the tag.
Positional parameters are as follows:
Parameters:
The title
The author's e-mail address (will create a tag if
present
A 'true' flag if you want to include a tag in the header. This
helps resolve relative addresses to absolute ones when the document
is moved, but makes the document hierarchy non-portable. Use with
care!
5, 6...
Any other parameters you want to include in the tag. This is
a good place to put Netscape extensions, such as colors and wallpaper
patterns.
ENDING THE HTML DOCUMENT:
-------------------------
print $query->end_html
This ends an HTML document by printing the tags.
CREATING FORMS:
===============
*General note* The various form-creating methods all return strings to
the caller, containing the tag or tags that will create the requested form
element. You are responsible for actually printing out these strings.
It's set up this way so that you can place formatting tags around the form
elements.
*Another note* The default values that you specify for the forms are
only used the first time the script is invoked. If there are already
values present in the query string, they are used, even if blank. If you
want to change the value of a field from its previous value, call the
param() method to set it.
*Yet another note* By default, the text and labels of form elements are
escaped according to HTML rules. This means that you can safely use
"" as the label for a button. However, it also interferes with
your ability to incorporate special HTML character sequences, such as
Á, into your fields. If you wish to turn off automatic escaping,
call the autoEscape() method with a false value immediately after creating
the CGI object:
$query = new CGI::Form;
$query->autoEscape(undef);
CREATING AN ISINDEX TAG
-----------------------
print $query->isindex($action);
Prints out an tag. Not very exciting. The optional
parameter specifies an ACTION="" attribute.
STARTING AND ENDING A FORM
--------------------------
print $query->startform($method,$action,$encoding);
<... various form stuff ...>
print $query->endform;
startform() will return a tag.
CREATING A TEXT FIELD
---------------------
print $query->textfield(-name=>'field_name',
-default=>'starting value',
-size=>50,
-maxlength=>80);
-or-
print $query->textfield('field_name','starting value',50,80);
textfield() will return a text input field.
Parameters
The first parameter is the required name for the field (-name).
The optional second parameter is the default starting value for the
field contents (-default).
The optional third parameter is the size of the field in
characters (-size).
The optional fourth parameter is the maximum number of characters the
field will accept (-maxlength).
As with all these methods, the field will be initialized with its
previous contents from earlier invocations of the script. When the form
is processed, the value of the text field can be retrieved with:
$value = $query->param('foo');
If you want to reset it from its initial value after the script has been
called once, you can do so like this:
$query->param('foo',"I'm taking over this value!");
CREATING A BIG TEXT FIELD
-------------------------
print $query->textarea(-name=>'foo',
-default=>'starting value',
-rows=>10,
-columns=>50);
-or
print $query->textarea('foo','starting value',10,50);
textarea() is just like textfield, but it allows you to specify rows
and columns for a multiline text entry box. You can provide a starting
value for the field, which can be long and contain multiple lines.
CREATING A PASSWORD FIELD
-------------------------
print $query->password_field(-name=>'secret',
-value=>'starting value',
-size=>50,
-maxlength=>80);
-or-
print $query->password_field('secret','starting value',50,80);
password_field() is identical to textfield(), except that its contents
will be starred out on the web page.
CREATING A FILE UPLOAD FIELD
----------------------------
print $query->filefield(-name=>'uploaded_file',
-default=>'starting value',
-size=>50,
-maxlength=>80);
-or-
print $query->filefield('uploaded_file','starting value',50,80);
filefield() will return a file upload field for Netscape 2.0 browsers.
In order to take full advantage of this *you must use the new multipart
encoding scheme* for the form. You can do this either by calling
*startform()* with an encoding type of *$CGI::MULTIPART*, or by calling
the new method *start_multipart_form()* instead of vanilla *startform()*.
Parameters
The first parameter is the required name for the field (-name).
The optional second parameter is the starting value for the field
contents to be used as the default file name (-default).
The beta2 version of Netscape 2.0 currently doesn't pay any attention
to this field, and so the starting value will always be blank. Worse,
the field loses its "sticky" behavior and forgets its previous
contents. The starting value field is called for in the HTML
specification, however, and possibly later versions of Netscape will
honor it.
The optional third parameter is the size of the field in characters
(-size).
The optional fourth parameter is the maximum number of characters the
field will accept (-maxlength).
When the form is processed, you can retrieve the entered filename by
calling param().
$filename = $query->param('uploaded_file');
In Netscape Beta 1, the filename that gets returned is the full local
filename on the *remote user's* machine. If the remote user is on a Unix
machine, the filename will follow Unix conventions:
/path/to/the/file
On an MS-DOS/Windows machine, the filename will follow DOS conventions:
C:\PATH\TO\THE\FILE.MSW
On a Macintosh machine, the filename will follow Mac conventions:
HD 40:Desktop Folder:Sort Through:Reminders
In Netscape Beta 2, only the last part of the file path (the filename
itself) is returned. I don't know what the release behavior will be.
The filename returned is also a file handle. You can read the contents
of the file using standard Perl file reading calls:
# Read a text file and print it out
while (<$filename>) {
print;
}
# Copy a binary file to somewhere safe
open (OUTFILE,">>/usr/local/web/users/feedback");
while ($bytesread=read($filename,$buffer,1024)) {
print OUTFILE $buffer;
}
CREATING A POPUP MENU
---------------------
print $query->popup_menu('menu_name',
['eenie','meenie','minie'],
'meenie');
-or-
%labels = ('eenie'=>'your first choice',
'meenie'=>'your second choice',
'minie'=>'your third choice');
print $query->popup_menu('menu_name',
['eenie','meenie','minie'],
'meenie',\%labels);
-or (named parameter style)-
print $query->popup_menu(-name=>'menu_name',
-values=>['eenie','meenie','minie'],
-default=>'meenie',
-labels=>\%labels);
popup_menu() creates a menu.
1. The required first argument is the menu's name (-name).
2. The required second argument (-values) is an array reference
containing the list of menu items in the menu. You can pass the
method an anonymous array, as shown in the example, or a reference to
a named array, such as "\@foo".
3. The optional third parameter (-default) is the name of the default
menu choice. If not specified, the first item will be the default.
The values of the previous choice will be maintained across queries.
4. The optional fourth parameter (-labels) is provided for people who
want to use different values for the user-visible label inside the
popup menu nd the value returned to your script. It's a pointer to an
associative array relating menu values to user-visible labels. If you
leave this parameter blank, the menu values will be displayed by
default. (You can also leave a label undefined if you want to).
When the form is processed, the selected value of the popup menu
can be retrieved using:
$popup_menu_value = $query->param('menu_name');
CREATING A SCROLLING LIST
-------------------------
print $query->scrolling_list('list_name',
['eenie','meenie','minie','moe'],
['eenie','moe'],5,'true');
-or-
print $query->scrolling_list('list_name',
['eenie','meenie','minie','moe'],
['eenie','moe'],5,'true',
\%labels);
-or-
print $query->scrolling_list(-name=>'list_name',
-values=>['eenie','meenie','minie','moe'],
-default=>['eenie','moe'],
-size=>5,
-multiple=>'true',
-labels=>\%labels);
scrolling_list() creates a scrolling list.
Parameters:
The first and second arguments are the list name (-name) and values
(-values). As in the popup menu, the second argument should be an
array reference.
The optional third argument (-default) can be either a reference to a
list containing the values to be selected by default, or can be a
single value to select. If this argument is missing or undefined,
then nothing is selected when the list first appears. In the named
parameter version, you can use the synonym "-defaults" for this
parameter.
The optional fourth argument is the size of the list (-size).
The optional fifth argument can be set to true to allow multiple
simultaneous selections (-multiple). Otherwise only one selection
will be allowed at a time.
The optional sixth argument is a pointer to an associative array
containing long user-visible labels for the list items (-labels). If
not provided, the values will be displayed.
When this form is procesed, all selected list items will be returned
as a list under the parameter name 'list_name'. The values of the
selected items can be retrieved with:
@selected = $query->param('list_name');
CREATING A GROUP OF RELATED CHECKBOXES
--------------------------------------
print $query->checkbox_group(-name=>'group_name',
-values=>['eenie','meenie','minie','moe'],
-default=>['eenie','moe'],
-linebreak=>'true',
-labels=>\%labels);
print $query->checkbox_group('group_name',
['eenie','meenie','minie','moe'],
['eenie','moe'],'true',\%labels);
HTML3-COMPATIBLE BROWSERS ONLY:
print $query->checkbox_group(-name=>'group_name',
-values=>['eenie','meenie','minie','moe'],
-rows=2,-columns=>2);
checkbox_group() creates a list of checkboxes that are related by the
same name.
Parameters:
The first and second arguments are the checkbox name and values,
respectively (-name and -values). As in the popup menu, the second
argument should be an array reference. These values are used for the
user-readable labels printed next to the checkboxes as well as for the
values passed to your script in the query string.
The optional third argument (-default) can be either a reference to a
list containing the values to be checked by default, or can be a
single value to checked. If this argument is missing or undefined,
then nothing is selected when the list first appears.
The optional fourth argument (-linebreak) can be set to true to place
line breaks between the checkboxes so that they appear as a vertical
list. Otherwise, they will be strung together on a horizontal line.
The optional fifth argument is a pointer to an associative array
relating the checkbox values to the user-visible labels that will will
be printed next to them (-labels). If not provided, the values will
be used as the default.
*HTML3-compatible browsers* (such as Netscape) can take advantage of
the optional parameters *-rows*, and *-columns*. These parameters
cause checkbox_group() to return an HTML3 compatible table containing
the checkbox group formatted with the specified number of rows and
columns. You can provide just the -columns parameter if you wish;
checkbox_group will calculate the correct number of rows for you.
To include row and column headings in the returned table, you can use
the *-rowheader* and *-colheader* parameters. Both of these accept a
pointer to an array of headings to use. The headings are just
decorative. They don't reorganize the interpetation of the
checkboxes - they're still a single named unit.
When the form is processed, all checked boxes will be returned as a
list under the parameter name 'group_name'. The values of the "on"
checkboxes can be retrieved with:
@turned_on = $query->param('group_name');
CREATING A STANDALONE CHECKBOX
------------------------------
print $query->checkbox(-name=>'checkbox_name',
-checked=>'checked',
-value=>'ON',
-label=>'CLICK ME');
-or-
print $query->checkbox('checkbox_name','checked','ON','CLICK ME');
checkbox() is used to create an isolated checkbox that isn't logically
related to any others.
Parameters:
The first parameter is the required name for the checkbox (-name). It
will also be used for the user-readable label printed next to the
checkbox.
The optional second parameter (-checked) specifies that the checkbox
is turned on by default. Synonyms are -selected and -on.
The optional third parameter (-value) specifies the value of the
checkbox when it is checked. If not provided, the word "on" is
assumed.
The optional fourth parameter (-label) is the user-readable label to
be attached to the checkbox. If not provided, the checkbox name is
used.
The value of the checkbox can be retrieved using:
$turned_on = $query->param('checkbox_name');
CREATING A RADIO BUTTON GROUP
-----------------------------
print $query->radio_group(-name=>'group_name',
-values=>['eenie','meenie','minie'],
-default=>'meenie',
-linebreak=>'true',
-labels=>\%labels);
-or-
print $query->radio_group('group_name',['eenie','meenie','minie'],
'meenie','true',\%labels);
HTML3-COMPATIBLE BROWSERS ONLY:
print $query->checkbox_group(-name=>'group_name',
-values=>['eenie','meenie','minie','moe'],
-rows=2,-columns=>2);
radio_group() creates a set of logically-related radio buttons (turning
one member of the group on turns the others off)
Parameters:
The first argument is the name of the group and is required (-name).
The second argument (-values) is the list of values for the radio
buttons. The values and the labels that appear on the page are
identical. Pass an array reference in the second argument, either
using an anonymous array, as shown, or by referencing a named array as
in "\@foo".
The optional third parameter (-default) is the name of the default
button to turn on. If not specified, the first item will be the
default. You can provide a nonexistent button name, such as "-" to
start up with no buttons selected.
The optional fourth parameter (-linebreak) can be set to 'true' to put
line breaks between the buttons, creating a vertical list.
The optional fifth parameter (-labels) is a pointer to an associative
array relating the radio button values to user-visible labels to be
used in the display. If not provided, the values themselves are
displayed.
*HTML3-compatible browsers* (such as Netscape) can take advantage of
the optional parameters *-rows*, and *-columns*. These parameters
cause radio_group() to return an HTML3 compatible table containing
the radio group formatted with the specified number of rows and
columns. You can provide just the -columns parameter if you wish;
radio_group will calculate the correct number of rows for you.
To include row and column headings in the returned table, you can use
the *-rowheader* and *-colheader* parameters. Both of these accept a
pointer to an array of headings to use. The headings are just
decorative. They don't reorganize the interpetation of the radio
buttons - they're still a single named unit.
When the form is processed, the selected radio button can be retrieved
using:
$which_radio_button = $query->param('group_name');
CREATING A SUBMIT BUTTON
------------------------
print $query->submit(-name=>'button_name',
-value=>'value');
-or-
print $query->submit('button_name','value');
submit() will create the query submission button. Every form should
have one of these.
Parameters:
The first argument (-name) is optional. You can give the button a
name if you have several submission buttons in your form and you want
to distinguish between them. The name will also be used as the
user-visible label. Be aware that a few older browsers don't deal
with this correctly and never send back a value from a button.
The second argument (-value) is also optional. This gives the button
a value that will be passed to your script in the query string.
You can figure out which button was pressed by using different values
for each one:
$which_one = $query->param('button_name');
CREATING A RESET BUTTON
-----------------------
print $query->reset
reset() creates the "reset" button. Note that it restores the form to
its value from the last time the script was called, NOT necessarily to the
defaults.
CREATING A DEFAULT BUTTON
-------------------------
print $query->defaults('button_label')
defaults() creates a button that, when invoked, will cause the form to
be completely reset to its defaults, wiping out all the changes the user
ever made.
CREATING A HIDDEN FIELD
-----------------------
print $query->hidden(-name=>'hidden_name',
-default=>['value1','value2'...]);
-or-
print $query->hidden('hidden_name','value1','value2'...);
hidden() produces a text field that can't be seen by the user. It is
useful for passing state variable information from one invocation of the
script to the next.
Parameters:
The first argument is required and specifies the name of this field
(-name).
The second argument is also required and specifies its value
(-default). In the named parameter style of calling, you can provide
a single value here or a reference to a whole list
Fetch the value of a hidden field this way:
$hidden_value = $query->param('hidden_name');
Note, that just like all the other form elements, the value of a hidden
field is "sticky". If you want to replace a hidden field with some other
values after the script has been called once you'll have to do it manually:
$query->param('hidden_name','new','values','here');
CREATING A CLICKABLE IMAGE BUTTON
---------------------------------
print $query->image_button(-name=>'button_name',
-src=>'/source/URL',
-align=>'MIDDLE');
-or-
print $query->image_button('button_name','/source/URL','MIDDLE');
image_button() produces a clickable image. When it's clicked on the
position of the click is returned to your script as "button_name.x" and
"button_name.y", where "button_name" is the name you've assigned to it.
Parameters:
The first argument (-name) is required and specifies the name of this
field.
The second argument (-src) is also required and specifies the URL
The third option (-align, optional) is an alignment type, and may be TOP, BOTTOM or MIDDLE
Fetch the value of the button this way: $x =
$query->param('button_name.x'); $y = $query->param('button_name.y');
DEBUGGING:
==========
If you are running the script from the command line or in the perl
debugger, you can pass the script a list of keywords or parameter=value
pairs on the command line or from standard input (you don't have to worry
about tricking your script into reading from environment variables). You
can pass keywords like this:
your_script.pl keyword1 keyword2 keyword3
or this:
your_script.pl keyword1+keyword2+keyword3
or this:
your_script.pl name1=value1 name2=value2
or this:
your_script.pl name1=value1&name2=value2
or even as newline-delimited parameters on standard input.
When debugging, you can use quotes and backslashes to escape characters
in the familiar shell manner, letting you place spaces and other funny
characters in your parameter=value pairs:
your_script.pl name1='I am a long value' name2=two\ words
DUMPING OUT ALL THE NAME/VALUE PAIRS
------------------------------------
The dump() method produces a string consisting of all the query's
name/value pairs formatted nicely as a nested list. This is useful for
debugging purposes:
print $query->dump
Produces something that looks like:
name1
value1
value2
name2
value1
You can pass a value of 'true' to dump() in order to get it to print
the results out as plain text, suitable for incorporating into a
section.
FETCHING ENVIRONMENT VARIABLES
==============================
All the environment variables, such as REMOTE_HOST and HTTP_REFERER,
are available through the CGI::Base object. You can get at these
variables using with the cgi() method (inherited from CGI::Request):
$query->cgi->var('REMOTE_HOST');
AUTHOR INFORMATION
==================
This code is copyright 1995 by Lincoln Stein and the Whitehead
Institute for Biomedical Research. It may be used and modified freely. I
request, but do not require, that this credit appear in the code.
Address bug reports and comments to: lstein@genome.wi.mit.edu
A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT
================================================
#!/usr/local/bin/perl
use CGI::Form;
$query = new CGI::Form;
print $query->header;
print $query->start_html("Example CGI.pm Form");
print "
Example CGI.pm Form
\n";
&print_prompt($query);
&do_work($query);
&print_tail;
print $query->end_html;
sub print_prompt {
my($query) = @_;
print $query->startform;
print "What's your name? ";
print $query->textfield('name');
print $query->checkbox('Not my real name');
print "
Where can you find English Sparrows? ";
print $query->checkbox_group('Sparrow locations',
[England,France,Spain,Asia,Hoboken],
[England,Asia]);
print "
How far can they fly? ",
$query->radio_group('how far',
['10 ft','1 mile','10 miles','real far'],
'1 mile');
print "
What's your favorite color? ";
print $query->popup_menu('Color',['black','brown','red','yellow'],'red');
print $query->hidden('Reference','Monty Python and the Holy Grail');
print "
What have you got there? ";
print $query->scrolling_list('possessions',
['A Coconut','A Grail','An Icon',
'A Sword','A Ticket'],
undef,
10,
'true');
print "
Any parting comments? ";
print $query->textarea('Comments',undef,10,50);
print "
";
foreach $key ($query->param) {
print "$key -> ";
@values = $query->param($key);
print join(", ",@values)," \n";
}
}
sub print_tail {
print <
Lincoln D. Stein Home Page
END
}
BUGS
====
This module doesn't do as much as CGI.pm, and it takes longer to load.
Such is the price of flexibility.
SEE ALSO
========
*Note URI/URL: URI/URL,, *Note CGI/Request: CGI/Request,, *Note
CGI/MiniSvr: CGI/MiniSvr,, *Note CGI/Base: CGI/Base,, *Note CGI: CGI,