NNAAMMEE
CGI - Simple Common Gateway Interface Class
SSYYNNOOPPSSIISS
use CGI;
# the rest is too complicated for a synopsis; keep reading
AABBSSTTRRAACCTT
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).
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/
IINNSSTTAALLLLAATTIIOONN
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:
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.
DDEESSCCRRIIPPTTIIOONNCCRREEAATTIINNGGAANNEEWWQQUUEERRYYOOBBJJEECCTT::
$query = new CGI;
This will parse the input (from both POST and GET methods)
and store it into a perl5 object called $query.
CCRREEAATTIINNGGAANNEEWWQQUUEERRYYOOBBJJEECCTTFFRROOMMAANNIINNPPUUTTFFIILLEE
$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:
$empty_query = new CGI("");
-or-
$empty_query = new CGI({});
FFEETTCCHHIINNGGAALLIISSTTOOFFKKEEYYWWOORRDDSSFFRROOMMTTHHEEQQUUEERRYY::
@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.
FFEETTCCHHIINNGGTTHHEENNAAMMEESSOOFFAALLLLTTHHEEPPAARRAAMMEETTEERRSSPPAASSSSEEDDTTOOYYOOUURRSSCCRRIIPPTT::
@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).
FFEETTCCHHIINNGGTTHHEEVVAALLUUEEOORRVVAALLUUEESSOOFFAASSIINNGGLLEENNAAMMEEDDPPAARRAAMMEETTEERR::
@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.
SSEETTTTIINNGGTTHHEEVALUE(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:
$query->param(-name=>'foo',-values=>['an','array','of','values']);
-or-
$query->param(-name=>'foo',-value=>'the value');
AAPPPPEENNDDIINNGGAADDDDIITTIIOONNAALLVVAALLUUEESSTTOOAANNAAMMEEDDPPAARRAAMMEETTEERR::
$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.
IIMMPPOORRTTIINNGGAALLLLPPAARRAAMMEETTEERRSSIINNTTOOAANNAAMMEESSPPAACCEE::
$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 iimmppoorrtt(()). As of
version 2.20, this name has been removed completely to
avoid conflict with the built-in Perl module iimmppoorrtt
operator.
DDEELLEETTIINNGGAAPPAARRAAMMEETTEERRCCOOMMPPLLEETTEELLYY::
$query->delete('foo');
This completely clears a parameter. It sometimes useful
for resetting parameters that you don't want passed down
between script invocations.
DDEELLEETTIINNGGAALLLLPPAARRAAMMEETTEERRSS::
$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.
SSAAVVIINNGGTTHHEESSTTAATTEEOOFFTTHHEEFFOORRMMTTOOAAFFIILLEE::
$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!
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 nneeww. 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.
CCRREEAATTIINNGGAASSEELLFF--RREEFFEERREENNCCIINNGGUURRLLTTHHAATTPPRREESSEERRVVEESSSSTTAATTEEIINNFFOORRMMAATTIIOONN::
$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.
$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;
CCOOMMPPAATTIIBBIILLIITTYYWWIITTHHCCGGII--LLIIBB..PPLL
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.
CCAALLLLIINNGGCCGGIIFFUUNNCCTTIIOONNSSTTHHAATTTTAAKKEEMMUULLTTIIPPLLEEAARRGGUUMMEENNTTSS
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
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
uussee__nnaammeedd__ppaarraammeetteerrss(()) 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.
CCRREEAATTIINNGGTTHHEEHHTTTTPPHHEEAADDEERR::
print $query->header;
-or-
print $query->header('image/gif');
-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 --ttyyppee, --ssttaattuuss,
--eexxppiirreess, and --ccooookkiiee. 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
--eexxppiirreess 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 --ccooookkiiee 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 attributes such
as expiration time. Use the cookie() method to create and
retrieve session cookies.
The --nnpphh 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.
GGEENNEERRAATTIINNGGAARREEDDIIRREECCTTIIOONNIINNSSTTRRUUCCTTIIOONN
print $query->redirect('http://somewhere.else/in/movie/land');
redirects the browser elsewhere. If you use redirection
like this, you should nnoott 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 --nnpphh 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.
CCRREEAATTIINNGGTTHHEEHHTTMMLLHHEEAADDEERR::
print $query->start_html(-title=>'Secrets of the Pyramids',
-author=>'fred@capricorn.org',
-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',
'fred@capricorn.org','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 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 --xxbbaassee 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 --ttaarrggeett 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 --mmeettaa 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 hheeaaddeerr(()) 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 --ssttyyllee 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 --hheeaadd 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'})
]
);
JAVASCRIPTING: The --ssccrriipptt, --nnooSSccrriipptt, --oonnLLooaadd and
--oonnUUnnllooaadd parameters are used to add Netscape JavaScript
calls to your pages. --ssccrriipptt 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 --oonnLLooaadd and --oonnUUnnllooaadd 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 --ssccrriipptt
field:
$query = new CGI;
print $query->header;
$JSCRIPT=<'The Riddle of the Sphinx',
-script=>$JSCRIPT);
Use the --nnooSSccrriipptt 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 --ssccrriipptt parameter
containing one or more of -language, -src, or -code:
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:
PPaarraammeetteerrss::
1. The title
2. The author's e-mail address (will create 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!
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.
EENNDDIINNGGTTHHEEHHTTMMLLDDOOCCUUMMEENNTT::
print $query->end_html
This ends an HTML document by printing the </BODY></HTML>
tags.
CCRREEAATTIINNGGFFOORRMMSSGeneralnote 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.
Anothernote The default values that you specify for the
forms are only used the ffiirrsstt 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.
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);
Yetanothernote 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);
CCRREEAATTIINNGGAANNIISSIINNDDEEXXTTAAGG
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.
SSTTAARRTTIINNGGAANNDDEENNDDIINNGGAAFFOORRMM
print $query->startform(-method=>$method,
-action=>$action,
-encoding=>$encoding);
<... various form stuff ...>
print $query->endform;
-or-
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:
aapppplliiccaattiioonn//xx--wwwwww--ffoorrmm--uurrlleennccooddeedd
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
$$CCGGII::::UURRLL__EENNCCOODDEEDD.
mmuullttiippaarrtt//ffoorrmm--ddaattaa
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 $$CCGGII::::MMUULLTTIIPPAARRTT
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
ssttaarrtt__mmuullttiippaarrtt__ffoorrmm(()) instead of ssttaarrttffoorrmm(()).
JAVASCRIPTING: The --nnaammee and --oonnSSuubbmmiitt 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.
CCRREEAATTIINNGGAATTEEXXTTFFIIEELLDD
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.
PPaarraammeetteerrss
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 --oonnCChhaannggee, --oonnFFooccuuss,
--oonnBBlluurr and --oonnSSeelleecctt 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 text that is
selected.
CCRREEAATTIINNGGAABBIIGGTTEEXXTTFFIIEELLDD
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 --oonnCChhaannggee, --oonnFFooccuuss, --oonnBBlluurr and
--oonnSSeelleecctt parameters are recognized. See textfield().
CCRREEAATTIINNGGAAPPAASSSSWWOORRDDFFIIEELLDD
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 --oonnCChhaannggee, --oonnFFooccuuss, --oonnBBlluurr and
--oonnSSeelleecctt parameters are recognized. See textfield().
CCRREEAATTIINNGGAAFFIILLEEUUPPLLOOAADDFFIIEELLDD
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 youmustusethenewmultipartencodingscheme for the form.
You can do this either by calling ssttaarrttffoorrmm(()) with an
encoding type of $$CCGGII::::MMUULLTTIIPPAARRTT, or by calling the new
method ssttaarrtt__mmuullttiippaarrtt__ffoorrmm(()) instead of vanilla
ssttaarrttffoorrmm(()).
PPaarraammeetteerrss
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 rreemmootteeuusseerr''ss 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;
}
# 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 --oonnCChhaannggee, --oonnFFooccuuss, --oonnBBlluurr and
--oonnSSeelleecctt parameters are recognized. See textfield() for
details.
CCRREEAATTIINNGGAAPPOOPPUUPPMMEENNUU
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
rreeffeerreennccee 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: --oonnCChhaannggee, --oonnFFooccuuss, and --oonnBBlluurr. See the
textfield() section for details on when these handlers are
called.
CCRREEAATTIINNGGAASSCCRROOLLLLIINNGGLLIISSTT
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.
PPaarraammeetteerrss::
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: --oonnCChhaannggee, --oonnFFooccuuss, and --oonnBBlluurr. See
textfield() for the description of when these handlers are
called.
CCRREEAATTIINNGGAAGGRROOUUPPOOFFRREELLAATTEEDDCCHHEECCKKBBOOXXEESS
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.
PPaarraammeetteerrss::
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. HHTTMMLL33--ccoommppaattiibblleebbrroowwsseerrss (such as Netscape) can take
advantage of the optional parameters --rroowwss, and
--ccoolluummnnss. 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 --rroowwhheeaaddeerr and --ccoollhheeaaddeerr
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 --oonnCClliicckk
parameter. This 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.
CCRREEAATTIINNGGAASSTTAANNDDAALLOONNEECCHHEECCKKBBOOXX
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.
PPaarraammeetteerrss::
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 --oonnCClliicckk
parameter. See checkbox_group() for further details.
CCRREEAATTIINNGGAARRAADDIIOOBBUUTTTTOONNGGRROOUUPP
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->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)
PPaarraammeetteerrss::
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. HHTTMMLL33--ccoommppaattiibblleebbrroowwsseerrss (such as Netscape) can take
advantage of the optional parameters --rroowwss, and
--ccoolluummnnss. 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 --rroowwhheeaaddeerr and --ccoollhheeaaddeerr
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');
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);
CCRREEAATTIINNGGAASSUUBBMMIITTBBUUTTTTOONN
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.
PPaarraammeetteerrss::
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 nneevveerr 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 --oonnCClliicckk
parameter. See checkbox_group() for further details.
CCRREEAATTIINNGGAARREESSEETTBBUUTTTTOONN
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.
CCRREEAATTIINNGGAADDEEFFAAUULLTTBBUUTTTTOONN
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.
CCRREEAATTIINNGGAAHHIIDDDDEENNFFIIEELLDD
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.
PPaarraammeetteerrss::
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');
CCRREEAATTIINNGGAACCLLIICCKKAABBLLEEIIMMAAGGEEBBUUTTTTOONN
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.
JAVASCRIPTING: image_button() recognizes the --oonnCClliicckk
parameter. See checkbox_group() for further details.
PPaarraammeetteerrss::
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
3. 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');
CCRREEAATTIINNGGAAJJAAVVAASSCCRRIIPPTTAACCTTIIOONNBBUUTTTTOONN
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 --oonnCClliicckk parameter
will be executed. On non-Netscape browsers this form
element will probably not even display.
NNEETTSSCCAAPPEECCOOOOKKIIEESS
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:
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 ccooookkiiee(()) method:
$cookie = $query->cookie(-name=>'sessionID',
-value=>'xyzzy',
-expires=>'+1h',
-path=>'/cgi-bin/database',
-domain=>'.capricorn.org',
-secure=>1);
print $query->header(-cookie=>$cookie);
ccooookkiiee(()) creates a new cookie. Its parameters include:
--nnaammee
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.
--vvaalluuee
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);
--ppaatthh
The optional partial path for which this cookie will
be valid, as described above.
--ddoommaaiinn
The optional partial domain for which this cookie will
be valid, as described above.
--eexxppiirreess
The optional expiration date for this cookie. The
format is as described in the section on the hheeaaddeerr(())
method:
"+1h" one hour from now
--sseeccuurree
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 --vvaalluuee 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 to turn a
CGI parameter into a cookie, and vice-versa:
# turn a CGI parameter into a cookie
$c=$q->cookie(-name=>'answers',-value=>[$q->param('answers')]);
# vice-versa
$q->param(-name=>'answers',-value=>[$q->cookie('answers')]);
See the ccooookkiiee..ccggii example script for some ideas on how to
use cookies effectively.
NNOOTTEE:: There appear to be some (undocumented) restrictions
on Netscape cookies. In Netscape 2.01, at least, I
haven't been able to set more than three cookies at a
time. There may also be limits on the length of cookies.
If you need to store a lot of information, it's probably
better to create a unique session ID, store it in a
cookie, and use the session ID to locate an external
file/database saved on the server's side of the
connection.
WWOORRKKIINNGGWWIITTHHNNEETTSSCCAAPPEEFFRRAAMMEESS
It's possible for CGI.pm scripts to write into several
browser panels and windows using Netscape's frame
mechanism. There are three techniques for defining new
frames programmatically:
1. Create a <Frameset> document
After writing out the HTTP header, instead of creating
a standard HTML document using the start_html() call,
create a <FRAMESET> document that defines the frames
on the page. Specify your script(s) (with appropriate
parameters) as the SRC for each of the frames.
There is no specific support for creating <FRAMESET>
sections in CGI.pm, but the HTML is very simple to
write. See the frame documentation in Netscape's home
pages for details
http://home.netscape.com/assist/net_sites/frames.html
2. Specify the destination for the document in the HTTP
header
You may provide a --ttaarrggeett parameter to the header()
method:
print $q->header(-target=>'ResultsWindow');
This will tell Netscape to load the output of your
script into the frame named "ResultsWindow". If a
frame of that name doesn't already exist, Netscape
will pop up a new window and load your script's
document into that. There are a number of magic names
that you can use for targets. See the frame documents
on Netscape's home pages for details.
3. Specify the destination for the document in the <FORM>
tag
You can specify the frame to load in the FORM tag
itself. With CGI.pm it looks like this:
print $q->startform(-target=>'ResultsWindow');
When your script is reinvoked by the form, its output
will be loaded into the frame named "ResultsWindow".
If one doesn't already exist a new window will be
created.
The script "frameset.cgi" in the examples directory shows
one way to create pages in which the fill-out form and the
response live in side-by-side frames.
LLIIMMIITTEEDDSSUUPPPPOORRTTFFOORRCCAASSCCAADDIINNGGSSTTYYLLEESSHHEEEETTSS
CGI.pm has limited support for HTML3's cascading style
sheets (css). To incorporate a stylesheet into your
document, pass the start_html() method a --ssttyyllee parameter.
The value of this parameter may be a scalar, in which case
it is incorporated directly into a <STYLE> section, or it
may be a hash reference. In the latter case you should
provide the hash with one or more of --ssrrcc or --ccooddee. --ssrrcc
points to a URL where an externally-defined stylesheet can
be found. --ccooddee points to a scalar value to be
incorporated into a <STYLE> section. Style definitions in
--ccooddee override similarly-named ones in --ssrrcc, hence the
name "cascading."
To refer to a style within the body of your document, add
the --ccllaassss parameter to any HTML element:
print h1({-class=>'Fancy'},'Welcome to the Party');
Or define styles on the fly with the --ssttyyllee parameter:
print h1({-style=>'Color: red;'},'Welcome to Hell');
You may also use the new ssppaann(()) element to apply a style
to a section of text:
print span({-style=>'Color: red;'},
h1('Welcome to Hell'),
"Where did that handbasket get to?"
);
Note that you must import the ":html3" definitions to have
the ssppaann(()) method available. Here's a quick and dirty
example of using CSS's. See the CSS specification at
http://www.w3.org/pub/WWW/TR/Wd-css-1.html for more
information.
use CGI qw/:standard :html3/;
#here's a stylesheet incorporated directly into the page
$newStyle=<'CGI with Style',
-style=>{-src=>'http://www.capricorn.com/style/st1.css',
-code=>$newStyle}
);
print h1('CGI with Style'),
p({-class=>'Tip'},
"Better read the cascading style sheet spec before playing with this!"),
span({-style=>'color: magenta'},
"Look Mom, no hands!",
p(),
"Whooo wee!"
);
print end_html;
DDEEBBUUGGGGIINNGG
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"
DDUUMMPPIINNGGOOUUTTAALLLLTTHHEENNAAMMEE//VVAALLUUEEPPAAIIRRSS
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:
<UL>
<LI>name1
<UL>
<LI>value1
<LI>value2
</UL>
<LI>name2
<UL>
<LI>value1
</UL>
</UL>
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.
As a shortcut, as of version 1.56 you can interpolate the
entire CGI object into a string and it will be replaced
with the a nice HTML dump shown above:
$query=new CGI;
print "<H2>Current Values</H2> $query\n";
FFEETTCCHHIINNGGEENNVVIIRROONNMMEENNTTVVAARRIIAABBLLEESS
Some of the more useful environment variables can be
fetched through this interface. The methods are as
follows:
aacccceepptt(())
Return a list of MIME types that the remote browser
accepts. If you give this method a single argument
corresponding to a MIME type, as in
$query->accept('text/html'), it will return a floating
point value corresponding to the browser's preference
for this type from 0.0 (don't want) to 1.0. Glob
types (e.g. text/*) in the browser's accept list are
handled correctly.
rraaww__ccooookkiiee(())
Returns the HTTP_COOKIE variable, an HTTP extension
implemented by Netscape browsers version 1.1 and
higher. Cookies have a special format, and this
method call just returns the raw form (?cookie dough).
See cookie() for ways of setting and retrieving cooked
cookies.
uusseerr__aaggeenntt(())
Returns the HTTP_USER_AGENT variable. If you give
this method a single argument, it will attempt to
pattern match on it, allowing you to do something like
$query->user_agent(netscape);
ppaatthh__iinnffoo(())
Returns additional path information from the script
URL. E.G. fetching /cgi-
bin/your_script/additional/stuff will result in
$query->path_info() returning "additional/stuff".
NOTE: The Microsoft Internet Information Server is
broken with respect to additional path information.
If you use the Perl DLL library, the IIS server will
attempt to execute the additional path information as
a Perl script. If you use the ordinary file
associations mapping, the path information will be
present in the environment, but incorrect. The best
thing to do is to avoid using additional path
information in CGI scripts destined for use with IIS.
ppaatthh__ttrraannssllaatteedd(())
As per path_info() but returns the additional path
information translated into a physical path, e.g.
"/usr/local/etc/httpd/htdocs/additional/stuff".
The Microsoft IIS is broken with respect to the
translated path as well.
rreemmoottee__hhoosstt(())
Returns either the remote host name or IP address. if
the former is unavailable.
ssccrriipptt__nnaammee(()) Return the script name as a partial URL, for
self- refering scripts.
rreeffeerreerr(())
Return the URL of the page the browser was viewing
prior to fetching your script. Not available for all
browsers.
aauutthh__ttyyppee(())
Return the authorization/verification method in use
for this script, if any.
sseerrvveerr__nnaammee(())
Returns the name of the server, usually the machine's
host name.
vviirrttuuaall__hhoosstt(())
When using virtual hosts, returns the name of the host
that the browser attempted to contact
sseerrvveerr__ssooffttwwaarree(())
Returns the server software and version number.
rreemmoottee__<