CGI(3) CGI(3)
CGI - Simple Common Gateway Interface Class
use CGI;
# the rest is too complicated for a synopsis; keep reading
This perl library uses perl5 objects to make it easy to create Web fillout
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).
The current version of CGI.pm is available at
http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
ftp://ftp-genome.wi.mit.edu/pub/software/WWW/
CGI is a part of the base Perl installation. However, you may need to
install a newer version someday. Therefore:
To install this package, just change to the directory in which this file
is found and type the following:
perl Makefile.PL
make
make install
This will copy CGI.pm to your perl library directory for use by all perl
scripts. You probably must be root to do this. Now you can load the
CGI routines in your Perl scripts with the line:
use CGI;
If you don't have sufficient privileges to install CGI.pm in the Perl
library directory, you can put CGI.pm into some convenient spot, such as
your home directory, or in cgi-bin itself and prefix all Perl scripts
that call it with something along the lines of the following preamble:
use lib '/home/davis/lib';
use CGI;
If you are using a version of perl earlier than 5.002 (such as NT perl),
use this instead:
Page 1
CGI(3) CGI(3)
BEGIN {
unshift(@INC,'/home/davis/lib');
}
use CGI;
The CGI distribution also comes with a cute module called the CGI::Carp
manpage. It redefines the die(), warn(), confess() and croak() error
routines so that they write nicely formatted error messages into the
server's error log (or to the output stream of your choice). This avoids
long hours of groping through the error and access logs, trying to figure
out which CGI script is generating error messages. If you choose, you
can even have fatal error messages echoed to the browser to avoid the
annoying and uninformative "Server Error" message.
CREATING A NEW QUERY OBJECT:
$query = new CGI;
This will parse the input (from both POST and GET methods) and store it
into a perl5 object called $query.
CREATING A NEW QUERY OBJECT FROM AN INPUT FILE
$query = new CGI(INPUTFILE);
If you provide a file handle to the new() method, it will read parameters
from the file (or STDIN, or whatever). The file can be in any of the
forms describing below under debugging (i.e. a series of newline
delimited TAG=VALUE pairs will work). Conveniently, this type of file is
created by the save() method (see below). Multiple records can be saved
and restored.
Perl purists will be pleased to know that this syntax accepts references
to file handles, or even references to filehandle globs, which is the
"official" way to pass a filehandle:
$query = new CGI(\*STDIN);
You can also initialize the query object from an associative array
reference:
$query = new CGI( {'dinosaur'=>'barney',
'song'=>'I love you',
'friends'=>[qw/Jessica George Nancy/]}
);
or from a properly formatted, URL-escaped query string:
$query = new CGI('dinosaur=barney&color=purple');
To create an empty query, initialize it from an empty string or hash:
Page 2
CGI(3) CGI(3)
$empty_query = new CGI("");
-or$empty_query
= new CGI({});
FETCHING A LIST OF KEYWORDS FROM THE QUERY:
@keywords = $query->keywords
If the script was invoked as the result of an <ISINDEX> search, the
parsed keywords can be obtained as an array using the keywords() method.
FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:
@names = $query->param
If the script was invoked with a parameter list (e.g.
"name1=value1&name2=value2&name3=value3"), the param() method will return
the parameter names as a list. If the script was invoked as an <ISINDEX>
script, there will be a single parameter named 'keywords'.
NOTE: As of version 1.5, the array of parameter names returned will be in
the same order as they were submitted by the browser. Usually this order
is the same as the order in which the parameters are defined in the form
(however, this isn't part of the spec, and so isn't guaranteed).
FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:
@values = $query->param('foo');
-or
$value = $query->param('foo');
Pass the param() method a single argument to fetch the value of the named
parameter. If the parameter is multivalued (e.g. from multiple selections
in a scrolling list), you can ask to receive an array. Otherwise the
method will return a single value.
SETTING THE VALUE(S) OF A NAMED PARAMETER:
$query->param('foo','an','array','of','values');
This sets the value for the named parameter 'foo' to an array of values.
This is one way to change the value of a field AFTER the script has been
invoked once before. (Another way is with the -override parameter
accepted by all methods that generate form elements.)
param() also recognizes a named parameter style of calling described in
more detail later:
Page 3
CGI(3) CGI(3)
$query->param(-name=>'foo',-values=>['an','array','of','values']);
-or
$query->param(-name=>'foo',-value=>'the value');
APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:
$query->append(-name=>;'foo',-values=>['yet','more','values']);
This adds a value or list of values to the named parameter. The values
are appended to the end of the parameter if it already exists. Otherwise
the parameter is created. Note that this method only recognizes the
named argument calling syntax.
IMPORTING ALL PARAMETERS INTO A NAMESPACE:
$query->import_names('R');
This creates a series of variables in the 'R' namespace. For example,
$R::foo, @R:foo. For keyword lists, a variable @R::keywords will appear.
If no namespace is given, this method will assume 'Q'. WARNING: don't
import anything into 'main'; this is a major security risk!!!!
In older versions, this method was called import(). As of version 2.20,
this name has been removed completely to avoid conflict with the built-in
Perl module import operator.
DELETING A PARAMETER COMPLETELY:
$query->delete('foo');
This completely clears a parameter. It sometimes useful for resetting
parameters that you don't want passed down between script invocations.
DELETING ALL PARAMETERS:
$query->delete_all();
This clears the CGI object completely. It might be useful to ensure that
all the defaults are taken when you create a fill-out form.
SAVING THE STATE OF THE FORM TO A FILE:
$query->save(FILEHANDLE)
This will write the current state of the form to the provided filehandle.
You can read it back in by providing a filehandle to the new() method.
Note that the filehandle can be a file, a pipe, or whatever!
Page 4
CGI(3) CGI(3)
The format of the saved file is:
NAME1=VALUE1
NAME1=VALUE1'
NAME2=VALUE2
NAME3=VALUE3
=
Both name and value are URL escaped. Multi-valued CGI parameters are
represented as repeated names. A session record is delimited by a single
= symbol. You can write out multiple records and read them back in with
several calls to new. You can do this across several sessions by opening
the file in append mode, allowing you to create primitive guest books, or
to keep a history of users' queries. Here's a short example of creating
multiple session records:
use CGI;
open (OUT,">>test.out") || die;
$records = 5;
foreach (0..$records) {
my $q = new CGI;
$q->param(-name=>'counter',-value=>$_);
$q->save(OUT);
}
close OUT;
# reopen for reading
open (IN,"test.out") || die;
while (!eof(IN)) {
my $q = new CGI(IN);
print $q->param('counter'),"\n";
}
The file format used for save/restore is identical to that used by the
Whitehead Genome Center's data exchange format "Boulderio", and can be
manipulated and even databased using Boulderio utilities. See
http://www.genome.wi.mit.edu/genome_software/other/boulder.html
for further details.
CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:
$myself = $query->self_url;
print "<A HREF=$myself>I'm talking to myself.</A>";
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.
Page 5
CGI(3) CGI(3)
$myself = $query->self_url;
print "<A HREF=$myself#table1>See table 1</A>";
print "<A HREF=$myself#table2>See table 2</A>";
print "<A HREF=$myself#yourself>See for yourself</A>";
If you don't want to get the whole query string, call the method url() to
return just the URL for the script:
$myself = $query->url;
print "<A HREF=$myself>No query string in this baby!</A>\n";
You can also retrieve the unprocessed query string with query_string():
$the_string = $query->query_string;
COMPATIBILITY WITH CGI-LIB.PL
To make it easier to port existing programs that use cgi-lib.pl the
compatibility routine "ReadParse" is provided. Porting is simple:
OLD VERSION
require "cgi-lib.pl";
&ReadParse;
print "The value of the antique is $in{antique}.\n";
NEW VERSION
use CGI;
CGI::ReadParse
print "The value of the antique is $in{antique}.\n";
CGI.pm's ReadParse() routine creates a tied variable named %in, which can
be accessed to obtain the query variables. Like ReadParse, you can also
provide your own variable. Infrequently used features of ReadParse, such
as the creation of @in and $in variables, are not supported.
Once you use ReadParse, you can retrieve the query object itself this
way:
$q = $in{CGI};
print $q->textfield(-name=>'wow',
-value=>'does this really work?');
This allows you to start using the more interesting features of CGI.pm
without rewriting your old scripts from scratch.
CALLING CGI FUNCTIONS THAT TAKE MULTIPLE ARGUMENTS
In versions of CGI.pm prior to 2.0, 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.0, there's a better way to pass
arguments to the various CGI functions. In this style, you pass a series
Page 6
CGI(3) CGI(3)
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:
<INPUT TYPE="textfield" NAME="State" VALUE="gaseous"
JUSTIFICATION="RIGHT">
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 THE HTTP HEADER:
print $query->header;
-or
print $query->header('image/gif');
Page 7
CGI(3) CGI(3)
-or
print $query->header('text/html','204 No response');
-or
print $query->header(-type=>'image/gif',
-nph=>1,
-status=>'402 Payment required',
-expires=>'+3d',
-cookie=>$cookie,
-Cost=>'$2.00');
header() returns the Content-type: header. You can provide your own MIME
type if you choose, otherwise it defaults to text/html. An optional
second parameter specifies the status code and a human-readable message.
For example, you can specify 204, "No response" to create a script that
tells the browser to do nothing at all. If you want to add additional
fields to the header, just tack them on to the end:
print $query->header('text/html','200 OK','Content-Length: 3002');
The last example shows the named argument style for passing arguments to
the CGI methods using named parameters. Recognized parameters are -type,
-status, -expires, and -cookie. Any other parameters will be stripped of
their initial hyphens and turned into header fields, allowing you to
specify any HTTP header you desire.
Most browsers will not cache the output from CGI scripts. Every time the
browser reloads the page, the script is invoked anew. You can change
this behavior with the -expires parameter. When you specify an absolute
or relative expiration interval with this parameter, some browsers and
proxy servers will cache the script's output until the indicated
expiration date. The following forms are all valid for the -expires
field:
+30s 30 seconds from now
+10m ten minutes from now
+1h one hour from now
-1d yesterday (i.e. "ASAP!")
now immediately
+3M in three months
+10y in ten years time
Thursday, 25-Apr-96 00:40:33 GMT at the indicated time & date
(CGI::expires() is the static function call used internally that turns
relative time intervals into HTTP dates. You can call it directly if you
wish.)
The -cookie parameter generates a header that tells the browser to
provide a "magic cookie" during all subsequent transactions with your
script. Netscape cookies have a special format that includes interesting
Page 8
CGI(3) CGI(3)
attributes such as expiration time. Use the cookie() method to create
and retrieve session cookies.
The -nph parameter, if set to a true value, will issue the correct
headers to work with a NPH (no-parse-header) script. This is important
to use with certain servers, such as Microsoft Internet Explorer, which
expect all their scripts to be NPH.
GENERATING A REDIRECTION INSTRUCTION
print $query->redirect('http://somewhere.else/in/movie/land');
redirects the browser elsewhere. If you use redirection like this, you
should not print out a header as well. As of version 2.0, we produce
both the unofficial Location: header and the official URI: header. This
should satisfy most servers and browsers.
One hint I can offer is that relative links may not work correctly when
you generate a redirection to another document on your site. This is due
to a well-intentioned optimization that some servers use. The solution
to this is to use the full URL (including the http: part) of the document
you are redirecting to.
You can use named parameters:
print $query->redirect(-uri=>'http://somewhere.else/in/movie/land',
-nph=>1);
The -nph parameter, if set to a true value, will issue the correct
headers to work with a NPH (no-parse-header) script. This is important
to use with certain servers, such as Microsoft Internet Explorer, which
expect all their scripts to be NPH.
CREATING THE HTML HEADER:
print $query->start_html(-title=>'Secrets of the Pyramids',
-author=>'[email protected]',
-base=>'true',
-target=>'_blank',
-meta=>{'keywords'=>'pharaoh secret mummy',
'copyright'=>'copyright 1996 King Tut'},
-style=>{'src'=>'/styles/style1.css'},
-BGCOLOR=>'blue');
-or
print $query->start_html('Secrets of the Pyramids',
'[email protected]','true',
'BGCOLOR="blue"');
This will return a canned HTML header and the opening <BODY> tag. All
parameters are optional. In the named parameter form, recognized
Page 9
CGI(3) CGI(3)
parameters are -title, -author, -base, -xbase and -target (see below for
the explanation). Any additional parameters you provide, such as the
Netscape unofficial BGCOLOR attribute, are added to the <BODY> tag.
The argument -xbase allows you to provide an HREF for the <BASE> tag
different from the current location, as in
-xbase=>"http://home.mcom.com/"
All relative links will be interpreted relative to this tag.
The argument -target allows you to provide a default target frame for all
the links and fill-out forms on the page. See the Netscape documentation
on frames for details of how to manipulate this.
-target=>"answer_window"
All relative links will be interpreted relative to this tag. You add
arbitrary meta information to the header with the -meta argument. This
argument expects a reference to an associative array containing
name/value pairs of meta information. These will be turned into a series
of header <META> tags that look something like this:
<META NAME="keywords" CONTENT="pharaoh secret mummy">
<META NAME="description" CONTENT="copyright 1996 King Tut">
There is no support for the HTTP-EQUIV type of <META> tag. This is
because you can modify the HTTP header directly with the header() method.
For example, if you want to send the Refresh: header, do it in the
header() method:
print $q->header(-Refresh=>'10; URL=http://www.capricorn.com');
The -style tag is used to incorporate cascading stylesheets into your
code. See the section on CASCADING STYLESHEETS for more information.
You can place other arbitrary HTML elements to the <HEAD> section with
the -head tag. For example, to place the rarely-used <LINK> element in
the head section, use this:
print $q->header(-head=>link({-rel=>'next',
-href=>'http://www.capricorn.com/s2.html'}));
To incorporate multiple HTML elements into the <HEAD> section, just pass
an array reference:
print $q->header(-head=>[ link({-rel=>'next',
-href=>'http://www.capricorn.com/s2.html'}),
link({-rel=>'previous',
-href=>'http://www.capricorn.com/s1.html'})
]
);
Page 10
CGI(3) CGI(3)
JAVASCRIPTING: The -script, -noScript, -onLoad and -onUnload parameters
are used to add Netscape JavaScript calls to your pages. -script should
point to a block of text containing JavaScript function definitions.
This block will be placed within a <SCRIPT> block inside the HTML (not
HTTP) header. The block is placed in the header in order to give your
page a fighting chance of having all its JavaScript functions in place
even if the user presses the stop button before the page has loaded
completely. CGI.pm attempts to format the script in such a way that
JavaScript-naive browsers will not choke on the code: unfortunately
there are some browsers, such as Chimera for Unix, that get confused by
it nevertheless.
The -onLoad and -onUnload parameters point to fragments of JavaScript
code to execute when the page is respectively opened and closed by the
browser. Usually these parameters are calls to functions defined in the
-script field:
$query = new CGI;
print $query->header;
$JSCRIPT=<<END;
// Ask a silly question
function riddle_me_this() {
var r = prompt("What walks on four legs in the morning, " +
"two legs in the afternoon, " +
"and three legs in the evening?");
response(r);
}
// Get a silly answer
function response(answer) {
if (answer == "man")
alert("Right you are!");
else
alert("Wrong! Guess again.");
}
END
print $query->start_html(-title=>'The Riddle of the Sphinx',
-script=>$JSCRIPT);
Use the -noScript parameter to pass some HTML text that will be displayed
on browsers that do not have JavaScript (or browsers where JavaScript is
turned off).
Netscape 3.0 recognizes several attributes of the <SCRIPT> tag, including
LANGUAGE and SRC. The latter is particularly interesting, as it allows
you to keep the JavaScript code in a file or CGI script rather than
cluttering up each page with the source. To use these attributes pass a
HASH reference in the -script parameter containing one or more of
-language, -src, or -code:
Page 11
CGI(3) CGI(3)
print $q->start_html(-title=>'The Riddle of the Sphinx',
-script=>{-language=>'JAVASCRIPT',
-src=>'/javascript/sphinx.js'}
);
print $q->(-title=>'The Riddle of the Sphinx',
-script=>{-language=>'PERLSCRIPT'},
-code=>'print "hello world!\n;"'
);
See
http://home.netscape.com/eng/mozilla/2.0/handbook/javascript/
for more information about JavaScript.
The old-style positional parameters are as follows:
Parameters:
1. The title
2. The author's e-mail address (will create a <LINK REV="MADE"> tag if
present
3. A 'true' flag if you want to include a <BASE> 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!
4, 5, 6...
Any other parameters you want to include in the <BODY> 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 </BODY></HTML> tags.
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 (when there is no query
string). On subsequent invocations of the script (when there is a query
string), the former values are used even if they are blank.
Page 12
CGI(3) CGI(3)
If you want to change the value of a field from its previous value, you
have two choices:
(1) call the param() method to set it.
(2) use the -override (alias -force) parameter (a new feature in version
2.15). This forces the default value to be used, regardless of the
previous value:
print $query->textfield(-name=>'field_name',
-default=>'starting value',
-override=>1,
-size=>50,
-maxlength=>80);
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:
$query = new CGI;
$query->autoEscape(undef);
CREATING AN ISINDEX TAG [Toc] [Back]
print $query->isindex(-action=>$action);
-or
print $query->isindex($action);
Prints out an <ISINDEX> tag. Not very exciting. The parameter -action
specifies the URL of the script to process the query. The default is to
process the query with the current script.
STARTING AND ENDING A FORM [Toc] [Back]
print $query->startform(-method=>$method,
-action=>$action,
-encoding=>$encoding);
<... various form stuff ...>
print $query->endform;
-or
Page 13
CGI(3) CGI(3)
print $query->startform($method,$action,$encoding);
<... various form stuff ...>
print $query->endform;
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
endform() returns the closing </FORM> tag.
Startform()'s 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:
application/x-www-form-urlencoded
This is the older type of encoding used by all browsers prior to
Netscape 2.0. It is compatible with many CGI scripts and is suitable
for short fields containing text data. For your convenience, CGI.pm
stores the name of this encoding type in $CGI::URL_ENCODED.
multipart/form-data
This is the newer type of encoding introduced by Netscape 2.0. It is
suitable for forms that contain very large fields or that are
intended for transferring binary data. Most importantly, it enables
the "file upload" feature of Netscape 2.0 forms. For your
convenience, CGI.pm stores the name of this encoding type in
$CGI::MULTIPART
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 compatibility, 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().
JAVASCRIPTING: The -name and -onSubmit parameters are provided for use
with JavaScript. The -name parameter gives the form a name so that it
can be identified and manipulated by JavaScript functions. -onSubmit
should point to a JavaScript function that will be executed just before
the form is submitted to your server. You can use this opportunity to
check the contents of the form for consistency and completeness. If you
find something wrong, you can put up an alert box or maybe fix things up
yourself. You can abort the submission by returning false from this
function.
Usually the bulk of JavaScript functions are defined in a <SCRIPT> block
in the HTML header and -onSubmit points to one of these function call.
See start_html() for details.
Page 14
CGI(3) CGI(3)
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 [Toc] [Back]
1. The first parameter is the required name for the field (-name).
2. The optional second parameter is the default starting value for the
field contents (-default).
3. The optional third parameter is the size of the field in
characters (-size).
4. 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!");
NEW AS OF VERSION 2.15: If you don't want the field to take on its
previous value, you can force its current value by using the -override
(alias -force) parameter:
print $query->textfield(-name=>'field_name',
-default=>'starting value',
-override=>1,
-size=>50,
-maxlength=>80);
JAVASCRIPTING: You can also provide -onChange, -onFocus, -onBlur and
-onSelect parameters to register JavaScript event handlers. The onChange
handler will be called whenever the user changes the contents of the text
field. You can do text validation if you like. onFocus and onBlur are
called respectively when the insertion point moves into and out of the
text field. onSelect is called when the user changes the portion of the
Page 15
CGI(3) CGI(3)
text that is selected.
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.
JAVASCRIPTING: The -onChange, -onFocus, -onBlur and -onSelect parameters
are recognized. See textfield().
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.
JAVASCRIPTING: The -onChange, -onFocus, -onBlur and -onSelect parameters
are recognized. See textfield().
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().
Page 16
CGI(3) CGI(3)
Parameters [Toc] [Back]
1. The first parameter is the required name for the field (-name).
2. 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.
3. The optional third parameter is the size of the field in characters
(-size).
4. 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 Gold, 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 and OS/2 machines, 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
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;
}
Page 17
CGI(3) CGI(3)
# Copy a binary file to somewhere safe
open (OUTFILE,">>/usr/local/web/users/feedback");
while ($bytesread=read($filename,$buffer,1024)) {
print OUTFILE $buffer;
}
When a file is uploaded the browser usually sends along some information
along with it in the format of headers. The information usually includes
the MIME content type. Future browsers may send other information as
well (such as modification date and size). To retrieve this information,
call uploadInfo(). It returns a reference to an associative array
containing all the document headers.
$filename = $query->param('uploaded_file');
$type = $query->uploadInfo($filename)->{'Content-Type'};
unless ($type eq 'text/html') {
die "HTML FILES ONLY!";
}
If you are using a machine that recognizes "text" and "binary" data
modes, be sure to understand when and how to use them (see the Camel
book). Otherwise you may find that binary files are corrupted during file
uploads.
JAVASCRIPTING: The -onChange, -onFocus, -onBlur and -onSelect parameters
are recognized. See textfield() for details.
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.
Page 18
CGI(3) CGI(3)
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');
JAVASCRIPTING: popup_menu() recognizes the following event handlers:
-onChange, -onFocus, and -onBlur. See the textfield() section for
details on when these handlers are called.
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.
Page 19
CGI(3) CGI(3)
Parameters:
1. 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.
2. 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.
3. The optional fourth argument is the size of the list (-size).
4. 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.
5. 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 processed, 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');
JAVASCRIPTING: scrolling_list() recognizes the following event handlers:
-onChange, -onFocus, and -onBlur. See textfield() for the description of
when these handlers are called.
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);
Page 20
CGI(3) CGI(3)
checkbox_group() creates a list of checkboxes that are related by the
same name.
Parameters:
1. 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.
2. 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.
3. 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.
4. The optional fifth argument is a pointer to an associative array
relating the checkbox values to the user-visible labels that will be
printed next to them (-labels). If not provided, the values will be
used as the default.
5. 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 interpretation 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');
The value returned by checkbox_group() is actually an array of button
elements. You can capture them and use them within tables, lists, or in
other creative ways:
@h = $query->checkbox_group(-name=>'group_name',-values=>\@values);
&use_in_creative_way(@h);
JAVASCRIPTING: checkbox_group() recognizes the -onClick parameter. This
Page 21
CGI(3) CGI(3)
specifies a JavaScript code fragment or function call to be executed
every time the user clicks on any of the buttons in the group. You can
retrieve the identity of the particular button clicked on using the
"this" variable.
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:
1. 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.
2. The optional second parameter (-checked) specifies that the checkbox
is turned on by default. Synonyms are -selected and -on.
3. The optional third parameter (-value) specifies the value of the
checkbox when it is checked. If not provided, the word "on" is
assumed.
4. 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');
JAVASCRIPTING: checkbox() recognizes the -onClick parameter. See
checkbox_group() for further details.
CREATING A RADIO BUTTON GROUP
print $query->radio_group(-name=>'group_name',
-values=>['eenie','meenie','minie'],
-default=>'meenie',
-linebreak=>'true',
-labels=>\%labels);
-or
Page 22
CGI(3) CGI(3)
print $query->radio_group('group_name',['eenie','meenie','minie'],
'meenie','true',\%labels);
HTML3-COMPATIBLE BROWSERS ONLY:
print $query->radio_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:
1. The first argument is the name of the group and is required (-name).
2. 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".
3. 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.
4. The optional fourth parameter (-linebreak) can be set to 'true' to
put line breaks between the buttons, creating a vertical list.
5. 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.
6. 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:
Page 23
CGI(3) CGI(3)
$which_radio_button = $query->param('group_name');
The value returned by radio_group() is actually an array of button
elements. You can capture them and use them within tables, lists, or in
other creative ways:
@h = $query->radio_group(-name=>'group_name',-values=>\@values);
&use_in_creative_way(@h);
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:
1. 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.
2. 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');
JAVASCRIPTING: radio_group() recognizes the -onClick parameter. See
checkbox_group() for further details.
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.
Page 24
CGI(3) CGI(3)
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:
1. The first argument is required and specifies the name of this field
(-name).
2. 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');
Page 25
CGI(3) CGI(3)
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.
JAVASCRIPTING: image_button() recognizes the -onClick parameter. See
checkbox_group() for further details.
Parameters:
1. The first argument (-name) is required and specifies the name of this
field.
2. The second argument (-src) is also required and specifies the URL
BOTTOM or MIDDLE
3. The third option (-align, optional) is an alignment type, and may be TOP,
Fetch the value of the button this way:
$x = $query->param('button_name.x');
$y = $query->param('button_name.y');
CREATING A JAVASCRIPT ACTION BUTTON
print $query->button(-name=>'button_name',
-value=>'user visible label',
-onClick=>"do_something()");
-or
print $query->button('button_name',"do_something()");
button() produces a button that is compatible with Netscape 2.0's
JavaScript. When it's pressed the fragment of JavaScript code pointed to
by the -onClick parameter will be executed. On non-Netscape browsers
this form element will probably not even display.
Netscape browsers versions 1.1 and higher support a so-called "cookie"
designed to help maintain state within a browser session. CGI.pm has
several methods that support cookies.
A cookie is a name=value pair much like the named parameters in a CGI
query string. CGI scripts create one or more cookies and send them to
the browser in the HTTP header. The browser maintains a list of cookies
that belong to a particular Web server, and returns them to the CGI
script during subsequent interactions.
In addition to the required name=value pair, each cookie has several
optional attributes:
Page 26
CGI(3) CGI(3)
1. an expiration time
This is a time/date string (in a special GMT format) that indicates
when a cookie expires. The cookie will be saved and returned to your
script until this expiration date is reached if the user exits
Netscape and restarts it. If an expiration date isn't specified, the
cookie will remain active until the user quits Netscape.
2. a domain
This is a partial or complete domain name for which the cookie is
valid. The browser will return the cookie to any host that matches
the partial domain name. For example, if you specify a domain name
of ".capricorn.com", then Netscape will return the cookie to Web
servers running on any of the machines "www.capricorn.com",
"www2.capricorn.com", "feckless.capricorn.com", etc. Domain names
must contain at least two periods to prevent attempts to match on top
level domains like ".edu". If no domain is specified, then the
browser will only return the cookie to servers on the host the cookie
originated from.
3. a path
If you provide a cookie path attribute, the browser will check it
against your script's URL before returning the cookie. For example,
if you specify the path "/cgi-bin", then the cookie will be returned
to each of the scripts "/cgi-bin/tally.pl", "/cgi-bin/order.pl", and
"/cgi-bin/customer_service/complain.pl", but not to the script
"/cgi-private/site_admin.pl". By default, path is set to "/", which
causes the cookie to be sent to any CGI script on your site.
4. a "secure" flag
If the "secure" attribute is set, the cookie will only be sent to
your script if the CGI request is occurring on a secure channel, such
as SSL.
The interface to Netscape cookies is the cookie() method:
$cookie = $query->cookie(-name=>'sessionID',
-value=>'xyzzy',
-expires=>'+1h',
-path=>'/cgi-bin/database',
-domain=>'.capricorn.org',
-secure=>1);
print $query->header(-cookie=>$cookie);
cookie() creates a new cookie. Its parameters include:
-name
The name of the cookie (required). This can be any string at all.
Although Netscape limits its cookie names to non-whitespace
alphanumeric characters, CGI.pm removes this restriction by escaping
and unescaping cookies behind the scenes.
Page 27
CGI(3) CGI(3)
-value
The value of the cookie. This can be any scalar value, array
reference, or even associative array reference. For example, you can
store an entire associative array into a cookie this way:
$cookie=$query->cookie(-name=>'family information',
-value=>\%childrens_ages);
-path
The optional partial path for which this cookie will be valid, as
described above.
-domain
The optional partial domain for which this cookie will be valid, as
described above.
-expires
The optional expiration date for this cookie. The format is as
described in the section on the header() method:
"+1h" one hour from now
-secure
If set to true, this cookie will only be used within a secure SSL
session.
The cookie created by cookie() must be incorporated into the HTTP header
within the string returned by the header() method:
print $query->header(-cookie=>$my_cookie);
To create multiple cookies, give header() an array reference:
$cookie1 = $query->cookie(-name=>'riddle_name',
-value=>"The Sphynx's Question");
$cookie2 = $query->cookie(-name=>'answers',
-value=>\%answers);
print $query->header(-cookie=>[$cookie1,$cookie2]);
To retrieve a cookie, request it by name by calling cookie() method
without the -value parameter:
use CGI;
$query = new CGI;
%answers = $query->cookie(-name=>'answers');
# $query->cookie('answers') will work too!
The cookie and CGI namespaces are separate. If you have a parameter
named 'answers' and a cookie named 'answers', the values retrieved by
param() and cookie() are independent of each other. However, it's simple
Page 28
CGI(3) CGI(3)
to turn a CGI parameter into a cookie, and vice-versa:
# turn a CGI parameter into a cookie
$c=$q->cookie(-name=
|
