MAN page from Old RedHat 5.X perl-5.004-4.i386.rpm
CGI
Section: Perl Programmers Reference Guide (3)
Updated: perl 5.004, patch 04
Index NAME
CGI - Simple Common Gateway Interface Class
SYNOPSIS
use CGI; # the rest is too complicated for a synopsis; keep reading
ABSTRACT
This perl library uses perl5 objects to make it easy to createWeb fill-out forms and parse their contents. This packagedefines CGI objects, entities that contain the values of thecurrent query string and other state variables.Using a CGI object's methods, you can examine keywords and parameterspassed to your script, and create forms whose initial valuesare taken from the current query (thereby preserving stateinformation).
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/
INSTALLATION
CGI is a part of the base Perl installation. However, you may needto install a newer version someday. Therefore:
To install this package, just change to the directory in which thisfile 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 allperl scripts. You probably must be root to do this. Now you canload 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 Perllibrary directory, you can put CGI.pm into some convenient spot, suchas your home directory, or in cgi-bin itself and prefix all Perlscripts that call it with something along the lines of the followingpreamble:
use lib '/home/davis/lib'; use CGI;
If you are using a version of perl earlier than 5.002 (such as NT perl), usethis 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 routinesso that they write nicely formatted error messages into the server'serror log (or to the output stream of your choice). This avoids longhours of groping through the error and access logs, trying to figureout which CGI script is generating error messages. If you choose,you can even have fatal error messages echoed to the browser to avoidthe annoying and uninformative ``Server Error'' message.
DESCRIPTION
CREATING A NEW QUERY OBJECT:
$query = new CGI;
This will parse the input (from both
POST and
GET methods) and storeit 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, itwill read parameters from the file (or
STDIN, or whatever). Thefile 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 acceptsreferences 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 arrayreference:
$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({}); FETCHING A LIST OF KEYWORDS FROM THE QUERY:
@keywords = $query->keywords
If the script was invoked as the result of an <
ISINDEX> search, theparsed 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 thescript was invoked as an <
ISINDEX> script, there will be asingle parameter named `keywords'.
NOTE: As of version 1.5, the array of parameter names returned willbe 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 partof 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 thenamed parameter. If the parameter is multivalued (e.g. from multipleselections in a scrolling list), you can ask to receive an array. Otherwisethe 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 ofvalues. This is one way to change the value of a field
AFTERthe script has been invoked once before. (Another way is withthe -override parameter accepted by all methods that generateform elements.)
param() also recognizes a named parameter style of calling describedin more detail later:
$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. Thevalues are appended to the end of the parameter if it already exists.Otherwise the parameter is created. Note that this method onlyrecognizes 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 securityrisk!!!!
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-inPerl module import operator.
DELETING A PARAMETER COMPLETELY:
$query->delete('foo');This completely clears a parameter. It sometimes useful forresetting parameters that you don't want passed down betweenscript invocations.
DELETING ALL PARAMETERS:
$query->
delete_all();
This clears the CGI object completely. It might be useful to ensurethat 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 providedfilehandle. You can read it back in by providing a filehandleto 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 arerepresented as repeated names. A session record is delimited by asingle = symbol. You can write out multiple records and read themback in with several calls to
new. You can do this across severalsessions by opening the file in append mode, allowing you to createprimitive guest books, or to keep a history of users' queries. Here'sa 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 theWhitehead Genome Center's data exchange format ``Boulderio'', and can bemanipulated and even databased using Boulderio utilities. See
http://www.genome.wi.mit.edu/genome_software/other/boulder.htmlfor 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 reinvokethis script with all its state information intact. This is mostuseful when you want to jump around within the document usinginternal anchors but you don't want to disrupt the current contentsof 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, callthe 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.plthe compatibility routine ``ReadParse'' is provided. Porting issimple:
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. LikeReadParse, you can also provide your own variable. Infrequentlyused 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 itselfthis way:
$q = $in{CGI}; print $q->textfield(-name=>'wow', -value=>'does this really work?');This allows you to start using the more interesting featuresof
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 rememberthe proper order of arguments in
CGI function calls that accepted fiveor six different arguments. As of 2.0, there's a better way to passarguments to the various
CGI functions. In this style, you pass aseries 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 theexact order of the arguments, and if you leave out a parameter, inmost cases it will default to some reasonable value. If you providea parameter that the method doesn't recognize, it will usually dosomething useful with it, such as incorporating it into the
HTML formtag. For example if Netscape decides next week to add a new
JUSTIFICATION parameter to the text field tags, you can start usingthe 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. Aftercreating a
CGI object, call the
use_named_parameters() method witha nonzero value. This will tell
CGI.pm that you intend to use namedparameters 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. Soyou can leave it off subsequent parameters if you like. Something tobe wary of is the potential that a string constant like ``values'' willcollide with a keyword (and in fact it does!) While Perl usuallyfigures out when you're referring to a function and when you'rereferring to a string, you probably should put quotation marks aroundall string constants just to play it safe.
CREATING THE HTTP HEADER:
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. Anoptional second parameter specifies the status code and a human-readablemessage. For example, you can specify 204, ``No response'' to create ascript that tells the browser to do nothing at all. If you want toadd 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 argumentsto 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 intoheader fields, allowing you to specify any
HTTP header you desire.
Most browsers will not cache the output from CGI scripts. Every timethe browser reloads the page, the script is invoked anew. You canchange this behavior with the -expires parameter. When you specifyan absolute or relative expiration interval with this parameter, somebrowsers and proxy servers will cache the script's output until theindicated 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 turnsrelative time intervals into
HTTP dates. You can call it directly ifyou wish.)
The -cookie parameter generates a header that tells the browser to providea ``magic cookie'' during all subsequent transactions with your script.Netscape cookies have a special format that includes interesting attributessuch as expiration time. Use the cookie() method to create and retrievesession cookies.
The -nph parameter, if set to a true value, will issue the correctheaders to work with a NPH (no-parse-header) script. This is importantto use with certain servers, such as Microsoft Internet Explorer, whichexpect 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, weproduce 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 correctlywhen 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 correctheaders to work with a
NPH (no-parse-header) script. This is importantto use with certain servers, such as Microsoft Internet Explorer, whichexpect all their scripts to be
NPH.
CREATING THE HTML HEADER:
print $query->start_html(-title=>'Secrets of the Pyramids', -author=>'fredAATTcapricorn.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', 'fredAATTcapricorn.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, recognizedparameters are -title, -author, -base, -xbase and -target (see below for theexplanation). Any additional parameters you provide, such as theNetscape unofficial
BGCOLOR attribute, are added to the <
BODY> tag.
The argument -xbase allows you to provide an HREF for the <BASE> tagdifferent 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 framefor all the links and fill-out forms on the page. See the Netscapedocumentation 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
-metaargument. This argument expects a reference to an associative arraycontaining name/value pairs of meta information. These will be turnedinto 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 isbecause you can modify the
HTTP header directly with the
header()method. For example, if you want to send the Refresh: header, do itin the
header() method:
print $q->header(-Refresh=>'10; URL=http://www.capricorn.com');
The
-style tag is used to incorporate cascading stylesheets intoyour 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 thehead 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 anarray 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
-script,
-noScript,
-onLoad and
-onUnload parametersare used to add Netscape JavaScript calls to your pages.
-scriptshould point to a block of text containing JavaScript functiondefinitions. This block will be placed within a <
SCRIPT> block insidethe
HTML (not
HTTP) header. The block is placed in the header inorder to give your page a fighting chance of having all its JavaScriptfunctions in place even if the user presses the stop button before thepage has loaded completely.
CGI.pm attempts to format the script insuch a way that JavaScript-naive browsers will not choke on the code:unfortunately there are some browsers, such as Chimera for Unix, thatget confused by it nevertheless.
The -onLoad and -onUnload parameters point to fragments of JavaScriptcode to execute when the page is respectively opened and closed by thebrowser. 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 turnedoff).
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 scriptrather than cluttering up each page with the source. To use theseattributes pass a HASH reference in the -script parameter containingone 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:
- 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. Thishelps 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 goodplace 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.
CREATING FORMS
General note The various form-creating methods all return stringsto the caller, containing the tag or tags that will create the requestedform element. You are responsible for actually printing out these strings.It's set up this way so that you can place formatting tagsaround the form elements.
Another note The default values that you specify for the forms are onlyused the first time the script is invoked (when there is no querystring). On subsequent invocations of the script (when there is a querystring), 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 twochoices:
(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 areescaped according to HTML rules. This means that you can safely use``<CLICK ME>'' as the label for a button. However, it also interferes withyour 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
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. Thedefault is to process the query with the current script.
STARTING AND ENDING A FORM
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 variousfields of the form before sending the form to the server. Twovalues are possible:
- application/x-www-form-urlencoded
- This is the older type of encoding used by all browsers prior toNetscape 2.0. It is compatible with many CGI scripts and issuitable for short fields containing text data. For yourconvenience, CGI.pm stores the name of this encodingtype 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 thatare intended for transferring binary data. Most importantly,it enables the ``file upload'' feature of Netscape 2.0 forms. Foryour convenience, CGI.pm stores the name of this encoding typein $CGI::MULTIPART
Forms that use this type of encoding are not easily interpretedby CGI scripts unless they use CGI.pm or another library designedto handle them.
For compatibility, the startform() method uses the older form ofencoding by default. If you want to use the newer form of encodingby default, you can call start_multipart_form() instead ofstartform().
JAVASCRIPTING: The -name and -onSubmit parameters are providedfor use with JavaScript. The -name parameter gives theform a name so that it can be identified and manipulated byJavaScript functions. -onSubmit should point to a JavaScriptfunction that will be executed just before the form is submitted to yourserver. You can use this opportunity to check the contents of the form for consistency and completeness. If you find something wrong, youcan 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 functioncall. See start_html() for details.
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
- 1.
- The first parameter is the required name for the field (-name).
- 2.
- The optional second parameter is the default starting value for the fieldcontents (-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 beretrieved with:
$value = $query->param('foo');If you want to reset it from its initial value after the script has beencalled 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 previousvalue, 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,
-onBlurand
-onSelect parameters to register JavaScript event handlers.The onChange handler will be called whenever the user changes thecontents of the text field. You can do text validation if you like.onFocus and onBlur are called respectively when the insertion pointmoves into and out of the text field. onSelect is called when theuser changes the portion of the 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 specifyrows and columns for a multiline text entry box. You can providea starting value for the field, which can be long and containmultiple lines.
JAVASCRIPTING: The -onChange, -onFocus, -onBlurand -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, -onBlurand -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 eitherby calling
startform() with an encoding type of
$CGI::MULTIPART,or by calling the new method
start_multipart_form() instead ofvanilla
startform().
- Parameters
- 1.
- The first parameter is the required name for the field (-name).
- 2.
- The optional second parameter is the starting value for the field contentsto be used as the default file name (-default).
The beta2 version of Netscape 2.0 currently doesn't pay any attentionto this field, and so the starting value will always be blank. Worse,the field loses its ``sticky'' behavior and forgets its previouscontents. The starting value field is called for in the HTMLspecification, however, and possibly later versions of Netscape willhonor it.
- 3.
- The optional third parameter is the size of the field incharacters (-size).
- 4.
- The optional fourth parameter is the maximum number of characters thefield will accept (-maxlength).
When the form is processed, you can retrieve the entered filenameby calling param().
$filename = $query->param('uploaded_file');In Netscape Gold, the filename that gets returned is the full local filenameon the
remote user's machine. If the remote user is on a Unixmachine, 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 contentsof 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 someinformation along with it in the format of headers. The informationusually includes the
MIME content type. Future browsers may sendother information as well (such as modification date and size). Toretrieve this information, call
uploadInfo(). It returns a reference toan 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'' datamodes, 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, -onBlurand -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.
- 1.
- The required first argument is the menu's name (-name).
- 2.
- The required second argument (-values) is an array referencecontaining the list of menu items in the menu. You can pass themethod an anonymous array, as shown in the example, or a reference toa named array, such as ``\@foo''.
- 3.
- The optional third parameter (-default) is the name of the defaultmenu 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 whowant to use different values for the user-visible label inside thepopup menu nd the value returned to your script. It's a pointer to anassociative array relating menu values to user-visible labels. If youleave this parameter blank, the menu values will be displayed bydefault. (You can also leave a label undefined if you want to).
When the form is processed, the selected value of the popup menu canbe 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.
- 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 anarray reference.
- 2.
- The optional third argument (-default) can be either a reference to alist containing the values to be selected by default, or can be asingle value to select. If this argument is missing or undefined,then nothing is selected when the list first appears. In the namedparameter version, you can use the synonym ``-defaults'' for thisparameter.
- 3.
- The optional fourth argument is the size of the list (-size).
- 4.
- The optional fifth argument can be set to true to allow multiplesimultaneous selections (-multiple). Otherwise only one selectionwill be allowed at a time.
- 5.
- The optional sixth argument is a pointer to an associative arraycontaining 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 asa list under the parameter name `list_name'. The values of theselected items can be retrieved with:
@selected = $query->param('list_name');
JAVASCRIPTING: scrolling_list() recognizes the following event handlers:-onChange, -onFocus, and -onBlur. See textfield() forthe 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);
checkbox_group() creates a list of checkboxes that are relatedby 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 secondargument should be an array reference. These values are used for theuser-readable labels printed next to the checkboxes as well as for thevalues passed to your script in the query string.
- 2.
- The optional third argument (-default) can be either a reference to alist containing the values to be checked by default, or can be asingle 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 placeline breaks between the checkboxes so that they appear as a verticallist. Otherwise, they will be strung together on a horizontal line.
- 4.
- The optional fifth argument is a pointer to an associative arrayrelating the checkbox values to the user-visible labels that willbe printed next to them (-labels). If not provided, the values willbe used as the default.
- 5.
- HTML3-compatible browsers (such as Netscape) can take advantage of the optional parameters -rows, and -columns. These parameters causecheckbox_group() to return an HTML3 compatible table containingthe checkbox group formatted with the specified number of rowsand columns. You can provide just the -columns parameter if youwish; checkbox_group will calculate the correct number of rowsfor you.
To include row and column headings in the returned table, youcan use the -rowheader and -colheader parameters. Bothof these accept a pointer to an array of headings to use.The headings are just decorative. They don't reorganize theinterpretation of the checkboxes -- they're still a single namedunit.
When the form is processed, all checked boxes will be returned asa 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 buttonelements. 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
-onClickparameter. This specifies a JavaScript code fragment orfunction call to be executed every time the user clicks onany of the buttons in the group. You can retrieve the identityof 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 logicallyrelated to any others.
- Parameters:
- 1.
- The first parameter is the required name for the checkbox (-name). Itwill also be used for the user-readable label printed next to thecheckbox.
- 2.
- The optional second parameter (-checked) specifies that the checkboxis turned on by default. Synonyms are -selected and -on.
- 3.
- The optional third parameter (-value) specifies the value of thecheckbox when it is checked. If not provided, the word ``on'' isassumed.
- 4.
- The optional fourth parameter (-label) is the user-readable label tobe attached to the checkbox. If not provided, the checkbox name isused.
The value of the checkbox can be retrieved using:
$turned_on = $query->param('checkbox_name');JAVASCRIPTING:
checkbox() recognizes the
-onClickparameter. 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-
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 radiobuttons. The values and the labels that appear on the page areidentical. Pass an array reference in the second argument, eitherusing an anonymous array, as shown, or by referencing a named array asin ``\@foo''.
- 3.
- The optional third parameter (-default) is the name of the defaultbutton to turn on. If not specified, the first item will be thedefault. You can provide a nonexistent button name, such as ``-'' tostart up with no buttons selected.
- 4.
- The optional fourth parameter (-linebreak) can be set to `true' to putline breaks between the buttons, creating a vertical list.
- 5.
- The optional fifth parameter (-labels) is a pointer to an associativearray relating the radio button values to user-visible labels to beused in the display. If not provided, the values themselves aredisplayed.
- 6.
- HTML3-compatible browsers (such as Netscape) can take advantage of the optional parameters -rows, and -columns. These parameters causeradio_group() to return an HTML3 compatible table containingthe radio group formatted with the specified number of rowsand columns. You can provide just the -columns parameter if youwish; radio_group will calculate the correct number of rowsfor you.
To include row and column headings in the returned table, youcan use the -rowheader and -colheader parameters. Bothof these accept a pointer to an array of headings to use.The headings are just decorative. They don't reorganize theinterpetation of the radio buttons -- they're still a single namedunit.
When the form is processed, the selected radio button canbe retrieved using:
$which_radio_button = $query->param('group_name');The value returned by
radio_group() is actually an array of buttonelements. 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 formshould have one of these.
- Parameters:
- 1.
- The first argument (-name) is optional. You can give the button aname if you have several submission buttons in your form and you wantto distinguish between them. The name will also be used as theuser-visible label. Be aware that a few older browsers don't deal with this correctly andnever send back a value from a button.
- 2.
- The second argument (-value) is also optional. This gives the buttona value that will be passed to your script in the query string.
You can figure out which button was pressed by using differentvalues for each one:
$which_one = $query->param('button_name');JAVASCRIPTING:
radio_group() recognizes the
-onClickparameter. See
checkbox_group() for further details.
CREATING A RESET BUTTON
print $query->reset
reset() creates the ``reset'' button. Note that it restores theform to its value from the last time the script was called,
NOT necessarily to the defaults.
CREATING A DEFAULT BUTTON
print $query->defaults('button_label')defaults() creates a button that, when invoked, will cause theform to be completely reset to its defaults, wiping out all thechanges 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. Itis useful for passing state variable information from one invocationof the script to the next.
- Parameters:
- 1.
- The first argument is required and specifies the name of thisfield (-name).
- 2.
- The second argument is also required and specifies its value(-default). In the named parameter style of calling, you can providea 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 ahidden field is ``sticky''. If you want to replace a hidden field withsome other values after the script has been called once you'll have todo it manually:
$query->param('hidden_name','new','values','here'); CREATING A CLICKABLE IMAGE BUTTON
print $query->image_button(-name=>'button_name', -src=>'/source/URL', -align=>'MIDDLE');
-or-
print $query->image_button('button_name','/source/URL','MIDDLE');image_button() produces a clickable image. When it's clicked on theposition of the click is returned to your script as ``button_name.x''and ``button_name.y'', where ``button_name'' is the name you've assignedto it.
JAVASCRIPTING: image_button() recognizes the -onClickparameter. See checkbox_group() for further details.
- Parameters:
- 1.
- The first argument (-name) is required and specifies the name of thisfield.
- 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 =
