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 CGI::Request. See its manpage for details. Similarly, CGI::Form uses CGI::Request to get and set named query parameters, e.g.
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:
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:
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.
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.
This method is actually defined in CGI::Base, but is passed through here for compatability with CGI.pm
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 CGI::Base.
NOTE: This is a temporary method that will be replaced by the CGI::Response module as soon as it is released.
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.
This will return a canned HTML header and the opening<BODY> 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<BODY> tag.
Positional parameters are as follows:
This ends an HTML document by printing the</BODY</HTML> tags.
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 <CLICK ME>" 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:
Prints out an<ISINDEX> tag. Not very exciting. The optional parameter specifies an ACTION=<URL>" attribute.
startform() will return a<FORM> tag with the optional method, action and form encoding that you specify. The defaults are: method: POST action: this script encoding: application/x-www-form-urlencoded
The encoding method tells the browser how to package the various fields of the form before sending the form to the server. Two values are possible:
Forms that use this type of encoding are not easily interpreted by CGI scripts unless they use CGI.pm or another library designed to handle them.
For compatability, the startform() method uses the older form of encoding by default. If you want to use the newer form of encoding by default, you can call start_multipart_form() instead of startform(). endform() returns a</FORM> tag.
textfield() will return a text input field.
If you want to reset it from its initial value after the script has been called once, you can do so like this:
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.
password_field() is identical to textfield(), except that its contents will be starred out on the web page.
filefield() will return a file upload field for Netscape 2.0 browsers.
In order to take full advantage of this I
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.
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:
On an MS-DOS/Windows machine, the filename will follow DOS conventions:
On a Macintosh machine, the filename will follow Mac conventions:
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:
popup_menu() creates a menu.
scrolling_list() creates a scrolling list.
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:
checkbox_group() creates a list of checkboxes that are related
by the same name.
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.
checkbox() is used to create an isolated checkbox that isn't logically
related to any others.
radio_group() creates a set of logically-related radio buttons
(turning one member of the group on turns the others off)
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.
submit() will create the query submission button. Every form
should have one of these.
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.
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.
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.
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:
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.
or this:
or this:
or this:
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:
Produces something that looks like:
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<PRE> section.
Address bug reports and comments to:
lstein@genome.wi.mit.edu
Where can you find English Sparrows? How far can they fly? 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? ",$query->reset;
print $query->submit('Action','Shout');
print $query->submit('Action','Scream');
print $query->endform;
print "
When the form is processed, you can retrieve the entered filename.by calling param().
# 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');
When the form is processed, the selected value of the popup menu can.be retrieved using:
CREATING A SCROLLING LIST
print $query->scrolling_list('list_name',
['eenie','meenie','minie','moe'],
['eenie','moe'],5,'true');
-or-
.
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);
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:
CREATING A STANDALONE CHECKBOX
print $query->checkbox(-name=>'checkbox_name',
-checked=>'checked',
-value=>'ON',
-label=>'CLICK ME');
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);
When the form is processed, the selected radio button can.be retrieved using:
CREATING A SUBMIT BUTTON
print $query->submit(-name=>'button_name',
-value=>'value');
You can figure out which button was pressed by using different.values for each one:
CREATING A RESET BUTTON
print $query->reset
CREATING A DEFAULT BUTTON
print $query->defaults('button_label')
CREATING A HIDDEN FIELD
print $query->hidden(-name=>'hidden_name',
-default=>['value1','value2'...]);
Fetch the value of a hidden field this way:.
$hidden_value = $query->param('hidden_name');
CREATING A CLICKABLE IMAGE BUTTON
print $query->image_button(-name=>'button_name',
-src=>'/source/URL',
-align=>'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:
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:
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):
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.
A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT
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 "
";
print $query->checkbox_group('Sparrow locations',
[England,France,Spain,Asia,Hoboken],
[England,Asia]);
print "
",
$query->radio_group('how far',
['10 ft','1 mile','10 miles','real far'],
'1 mile');
print "
";
print $query->textarea('Comments',undef,10,50);
print "
\n";
}
sub do_work {
my($query) = @_;
my(@values,$key);
print "Here are the current settings in this form
";
foreach $key ($query->param) {
print <STRONG>$ke</STRONG> -> ";
@values = $query->param($key);
print join(", ",@values),<BR>\n";
}
}
sub print_tail {
print <<END;
<HR>
<ADDRESS>Lincoln D. Stei</ADDRESS<BR>
<A HREF="/">Home Pag</A>
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
URI::URL, CGI::Request, CGI::MiniSvr, CGI::Base, CG/EM