home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book HomeWebmaster in a Nutshell, 3rd EditionSearch this book

14.7. CGI.pm Reference

The following methods are supported by CGI.pm.

Accept

$query->accept(['content_type'])

Returns a list of media types that the browser accepts.

content_type
If specified, returns instead the browser's preference for the specified content type, between 0.0 and 1.0.

append

$query->append(-name=>'name',-values=>'value')

Appends a value or list of values to the named parameter.

-name=>'name'
The parameter to be appended.

-values=>'value'
The value to append. Multiple values can be specified as a reference to an anonymous array.

autoEscape

$query->autoEscape(undef)

Turns off autoescaping of form elements.

button

print $query->button('name','function')

Generates a JavaScript button.

name
The name of the button.

function
The function to execute when the button is clicked.

Using named parameters, the syntax is:

print $query->button(-name=>'name',
                      -value=>'label',
                      -onClick=>"function");
-value=>'label'
The label to display for the button.

checkbox

print $query->checkbox('name' [,'checked','value','label'])

Generates a single checkbox.

name
The name to assign the input to (required).

checked
Checkbox should be checked initially.

value
The value to return when checked (default is on).

label
The label to use for the checkbox (default is the name of the checkbox).

Using named parameters, the syntax is:

print $query->checkbox(-name=>'name',
                          -checked=>'checked',
                          -value=>'value',
                          -label=>'label',
                          -onClick=>function);
onClick=>function
Browser should execute function when the user clicks on any checkbox in the group.

checkbox_group

print $query->checkbox_group('name', \@list [,selected, 'true',\%labelhash ])

Generates a list of checkbox elements.

name
The name to assign the input to (required).

\@list
An array reference with the list items. You can also use an anonymous array reference.

selected
The menu item(s) to be initially selected (default is that nothing is selected). This can be a single value or a reference to an array of values.

true
Insert newlines between the checkboxes.

\%labelhash
A hash reference listing labels for each list item. Default is the list text itself. See popup_menu for an example.

Using named parameters, the syntax is:

print $query->checkbox_group(-name=>'name',
                                -values=>\@list,
                                -default=>selected,
                                -linebreak=>'true',
                                -labels=>\%labelhash,
                                -columns=>n,
                                -columnheader=>'string',
                                -rows=>m,
                                -rowheader=>'string',
                                -onClick=>function);
-columns=>n
The number of columns to use.

-columnheader=>'string'
A header for the column.

-rows=m
The number of rows to use. If omitted and -columns is specified, the rows are calculated for you.

-rowheader=>'string'
A header for the row.

-onClick=>function
Browser should execute function when the user clicks on any checkbox in the group.

cookie

$cookie=$query->cookie('name')

Defines or retrieves a cookie. See also header .

name
Name of the cookie (required).

Using named parameters, the syntax is:

$cookie = $query->cookie(-name=>'name',
                         -value=>'value',
                         -expires=>'expcode',
                         -path=>'partial_url',
                         -domain=>'domain_name',
                         -secure=>1);
print $query->header(-cookie=>$cookie);
-value=>'value'
A value to assign to the cookie. You can supply a scalar value, or a reference to an array or hash. If omitted, a cookie is retrieved rather than defined.

-expires=>expcode
Specify an expiration timestamp (such as +3d for 3 days). Values for expcode are:

ns
n seconds

nm
n minutes

nh
n hours

nd
n days

nM
n months

nY
n years

day_of_week, dd-MMM-YY hh:mm:ss GMT
At the specified time

now
Expire immediately.

-path=>'partial_url'
The partial URL for which the cookie is valid. Default is the current URL.

-domain=>'domain_name'
The domain for which the cookie is valid.

-secure=>1
Only use this cookie for a secure session.

defaults

print $query->defaults('label')

Generates a button that resets the form to its defaults. See also reset.

label
The label to use for the button. If omitted, the label is "Defaults."

delete

$query->delete('parameter')

Deletes a parameter.

parameter
The parameter to delete.

delete_all

$query->delete_all( )

Deletes the entire CGI object.

dump

print $query->dump([true])

Dumps all name/value pairs as an HTML list.

true
If specified, print as plain text.

end_html

print $query->end_html( )

Ends an HTML document.

filefield

print $query->filefield('name' [,'default',size,maxlength])

Generates a file upload field for Netscape browsers.

name
The filename to assign the supplied file contents to (required).

default
The initial value (filename) to place in the text field.

size
The size of the text field (in characters).

maxlength
The maximum length of the text field (in characters).

Using named parameters, the syntax is:

print $query->textfield(-name=>'name',
                        -default=>'value',
                        -size=>size,
                        -maxlength=>maxlength,
                        -override=>1,
                        -onChange=>function,
                        -onFocus=>function,
                        -onBlur=>function,
                        -onSelect=>function);
-override=>1
Text field should not inherit its value from a previous invocation of the script.

-onChange=>function
Browser should execute function when the user changes the text field.

-onFocus=>function
Browser should execute function when the focus is on the text field.

-onBlur=>function
Browser should execute function when the focus leaves the text field.

-onSelect=>function
Browser should execute function when the user changes a selected portion of the text field.

header

print $query->header([content_type, status, headers])

Generates the HTTP header for the document.

content_type
The content type to return. Default is text/html.

status
The HTTP status code and description to return. Default is 200 OK.

headers
Additional headers to include, such as Content-Length: 123.

Using named parameters, the syntax is:

print $query->header(-type=>'content_type',
                              -nph=>1,
                              -status=>'status_code',
                              -expires=>'expcode',
                              -cookie=>'cookie',
                              -target=>'frame',
                              -header=>'value');
-type=>content_type
Specify the content type.

-nph=>1
Use headers for a no-parse-header script.

-status=>status_code
Specify the status code.

-expires=>expcode
Specify an expiration timestamp (such as +3d for 3 days). Values for expcode are:

ns
n seconds

nm
n minutes

nh
n hours

nd
n days

nM
n months

nY
n years

day_of_week, dd-MMM-YY hh:mm:ss GMT
At the specified time

now
Expire immediately.

-cookie=>cookie
Specify a cookie. The cookie may be a scalar value or an array reference.

-header=>value
Specify any HTTP header.

-target=>frame
Write to specified frame.

hidden

print $query->hidden('name', 'value' [,'value'... ])

Generates a hidden text field.

name
The name to give the value (required).

value
The value to assign to name. Multiple values can be specified.

Using named parameters, the syntax is:

print $query->hidden(-name=>'name',
                       -default=>'value');

With named parameters, the value can also be represented as a reference to an array, such as:

print $query->hidden(-name=>'name',
                     -default=>['value1', 'value2', ...  ]);
image_button

print $query->image_button('name','url' [,'align'])

Generates a clickable image map.

name
The name to use. When clicked, the x,y position is returned as name.x and name.y, respectively.

url
The URL of the image for the image map.

align
The alignment type. May be TOP, BOTTOM, or MIDDLE.

Using named parameters, the syntax is:

print $query->image_button(-name=>'name',
                            -src=>'url',
                            -align=>'align',
                            -onClick=>function);
-onClick=>function
Browser should execute function when the user clicks on the image.

import_names

$query->import_names('package')

Creates variables in the specified package. Called import in older versions of CGI.pm.

package
The package to import names into.

isindex

print $query->isindex([action])

Generates an <ISINDEX> tag.

action
The URL of the index script. Default is the current URL.

Using named parameters, the syntax is:

print $query->isindex(-action=>$action);
keywords

@keyarray = $query->keywords( )

Retrieves keywords from an <ISINDEX> search.

@keyarray
The array to contain the retrieved keywords.

nph

nph(1)

Treats a CGI script as a no-parsed-header (NPH) script.

param

@name = $query->param([parameter[newvalue1, newvalue2,...] ])

Gets or sets parameter names.

@name
The array to contain the parameter names.

parameter
An optional single parameter to fetch. When used with no arguments, param returns a list of all known parameter names.

newvalue1, newvalue2, ...
The optional new values to assign to the parameter.

Using named parameters, the syntax is:

$query->param(-name=>'parameter',
                   -value=>'newvalue');

or:

$query->param(-name=>'parameter',
                   -values=>'newvalue1', 'newvalue2', ...);
password_field

print $query->password_field('name' [,'value',size,maxlength])

Generates a password input field.

name
The name to assign the input to (required).

value
The default password to place in the password field.

size
The size of the password field (in characters).

maxlength
The maximum length of the password field (in characters).

Using named parameters, the syntax is:

print $query->password_field(-name=>'name',
                             -default=>'value',
                             -size=>size,
                             -maxlength=>maxlength,
                             -override=>1,
                             -onChange=>function,
                             -onFocus=>function,
                             -onBlur=>function,
                             -onSelect=>function);
-override=>1
Text field should not inherit its value from a previous invocation of the script.

-onChange=>function
Browser should execute function when the user changes the text field.

-onFocus=>function
Browser should execute function when the focus is on the text field.

-onBlur=>function
Browser should execute function when the focus leaves the text field.

-onSelect=>function
Browser should execute function when the user changes a selected portion of the text field.

path_info

path_info( )

Returns extra path information.

path_translated

path_translated( )

Returns translated extra path information.

popup_menu

print $query->popup_menu('name', \@array [,'selected', \%labelhash])

Generates a pop-up menu.

name
The name to assign the input to (required).

\@array
An array reference listing the menu items. You can also use an anonymous array reference (see the second example).

selected
The menu item to be initially selected (default is first menu item or the item selected in previous queries).

\%labelhash
A hash reference listing labels for each menu item. Default is menu item text. For example:

%labels = ('UPS'=>'United Parcel Service (UPS)',
    'FedExO'=>'Federal Express Overnight - 10AM delivery',
    'FedExS'=>'Federal Express Standard - 2PM delivery',
    'FedEx2'=>'Federal Express 2nd Day Delivery');

print $query->popup_menu('delivery_method', 
                    ['UPS', 'FedExO', 'FedExS', 'FedEx2'], 
                       'FedExO', 
                       \%labels);

Using named parameters, the syntax is:

print $query->popup_menu(-name=>'name',
                            -values=>\@array,
                            -default=>'selected',
                            -labels=>\%labelhash,
                            -onChange=>function,
                            -onFocus=>function,
                            -onBlur=>function);
-onChange=>function
Browser should execute function when the user changes the text field.

-onFocus=>function
Browser should execute function when the focus is on the text field.

-onBlur=>function
Browser should execute function when the focus leaves the text field.

radio_group

print $query->radio_group('name', \@list [, selected, 'true', \%label])

Generates a set of radio buttons.

name
The name to assign the input to (required).

\@list
An array reference with the list items. You can also use an anonymous array reference.

selected
The menu item to be initially selected.

true
Insert newlines between radio buttons.

\%label
A hash reference listing labels for each list item. Default is the list text itself. See popup_menu for an example.

Using named parameters, the syntax is:

print $query->radio_group(-name=>'name',
                             -values=>\@list,
                             -default=>'selected',
                             -linebreak=>'true',
                             -labels=>\%labelhash,
                             -columns=>n,
                             -columnheader=>'string',
                             -rows=>m,
                             -rowheader=>'string');
-columns=>n
The number of columns to use.

-columnheader=>'string'
A header for the column.

-rows=m
The number of rows to use. If omitted and -columns is specified, the rows are calculated for you.

-rowheader=>'string'
A header for the row.

raw_cookie

raw_cookie( )

Returns the value of the HTTP_COOKIE header.

ReadParse

ReadParse( )

Creates a hash named %in containing query information. Used for backward compatibility with the Perl4 cgi-lib.pl.

redirect

print $query->redirect('url')

Generates a header for redirecting the browser.

url
The absolute URL to redirect to.

Using named parameters, the syntax is:

print $query->redirect(-uri=>'url',
                       -nph=>1);
referer

referer( )

Returns the referring URL.

remote_host

remote_host( )

Returns the remote hostname or IP address, depending on the configuration of the server.

remote_user

remote_user( )

Returns the username supplied for authorization.

request_method

request_method( )

Returns the request method.

reset

print $query->reset

Generates a button that resets the form to its initial values. See also defaults.

save

$query->save(filehandle)

Saves the form to the specified filehandle, to be read back with the new constructor.

filehandle
The filehandle to save the file to.

script_name

script_name( )

Returns the current partial URL.

scrolling_list

print $query->scrolling_list('name',\@list [,selected,size,'true', \%labelhash])

Generates a scrolling list.

name
The name to assign the input to (required).

\@list
An array reference with the list items. You can also use an anonymous array reference.

selected
The menu item(s) to be initially selected (default is that nothing is selected). This can be a single value or a reference to a list of values.

size
The number of elements to display in the list box.

true
Allow multiple selections.

\%labelhash
A hash reference listing labels for each list item. Default is the list text itself. See popup_menu for an example.

Using named parameters, the syntax is:

print $query->scrolling_list(-name=>'name',
                                -values=>\@listarray,
                                -default=>selected,
                                -size=>size,
                                -multiple=>'true',
                                -labels=>\%labelhash,
                                -onChange=>function,
                                -onFocus=>function,
                                -onBlur=>function);
-onChange=>function
Browser should execute function when the user changes the text field.

-onFocus=>function
Browser should execute function when the focus is on the text field.

-onBlur=>function
Browser should execute function when the focus leaves the text field.

self_url

$url = $query->self_url

Returns the URL of the current script with all its state information intact.

start_html

print $query->start_html(['title', 'email', 'base', attribute='value'])

Generates <HTML> and <BODY> tags.

title
The title of the page.

email
The author's email address.

base
Whether to use a <BASE> tag in the header.

attribute='value'
Specifies an attribute to the <BODY> tag.

Using named parameters, the syntax is:

print $query->start_html(-title=>'title',
                            -author=>'email_address',
                            -base=>'true',
                            -xbase=>'url',
                            -meta=>{'metatag1'=>'value1',
                                    'metatag2'=>'value2'},
                            -script=>'$script',
                            -onLoad=>'$function',
                            -onUnload=>'$function',
                             attribute=>'value');
-title=>'title'
Specifies the title of the page.

-author=>'email_address'
Specifies the author's email address.

-xbase=>'url'
Provides an HREF for the <BASE> tag. Default is the current location.

-meta=>{'metatag1'=>'value1', ... }
Adds arbitrary meta information to the header as a reference to a hash. Valid tags are:

keywords
Keywords for this document.

copyright
Description for this document.

attribute=>'value'
Specify an attribute to the <BODY> tag.

-script=>'$script'
Specify a JavaScript script to be embedded within a <SCRIPT> block.

-onLoad=>'$function'
Browser should execute the specified function upon entering the page.

-onUnload=>'$function'
Browser should execute the specified function upon leaving the page.

startform

print $query->startform([method, action, encoding])

Generates a <FORM> tag.

method
The request method for the form. Values are:

POST
Use the POST method (default).

GET
Use the GET method.

action
The URL of the CGI script. Default is the current URL.

encoding
The encoding scheme. Possible values are application/x-www-form-urlencoded and multipart/form-data.

Using named parameters, the syntax is:

print $query->startform(-method=>$method,
                        -action=>$action,
                        -encoding=>$encoding,
                        -name=>$name,
                        -target=>frame,
                        -onSubmit=>function);
-name=>name
Names the form for identification by JavaScript functions.

-target=>frame
Writes to the specified frame.

-onSubmit=>function
A JavaScript function that the browser should execute upon submitting the form.

start_multipart_form

print $query->start_multipart_form([method, action])

Generates <HTML> and <BODY> tags. Same as startform but assumes multipart/form-data encoding as the default.

submit

print $query->submit([ 'label','value' ])

Generates a submit button.

label
The label to use for the button.

value
The value to return when the form is submitted.

Using named parameters, the syntax is:

print $query->submit(-name=>'name',
                  -value=>'value',
                  -onClick=>function);
-onClick=>function
Browser should execute function when the user clicks the Submit button.

textarea

print $query->textarea('name' [,'value',rows,columns ])

Generates a large multiline text input box.

name
The name to assign the input to (required).

value
The initial value to place into the text input box.

rows
The number of rows to display.

columns
The number of columns to display.

Using named parameters, the syntax is:

print $query->textarea(-name=>'name',
                          -default=>'value',
                          -rows=>rows,
                          -columns=>columns,
                          -override=>1,
                          -onChange=>function,
                          -onFocus=>function,
                          -onBlur=>function,
                          -onSelect=>function);
-override=>1
Text field should not inherit its value from a previous invocation of the script.

-onChange=>function
Browser should execute function when the user changes the text field.

-onFocus=>function
Browser should execute function when the focus is on on the text field.

-onBlur=>function
Browser should execute function when the focus leaves the text field.

-onSelect=>function
Browser should execute function when the user changes a selected portion of the text field.

textfield

print $query->textfield('name' [,'value', size, maxlength])

Generates a text input field.

name
The name to assign the input to (required).

value
The initial value to place in the text field.

size
The size of the text field (in characters).

maxlength
The maximum length of the text field (in characters).

Using named parameters, the syntax is:

print $query->textfield(-name=>'name',
                        -default=>'value',
                        -size=>size,
                        -maxlength=>maxlength,
                        -override=>1,
                        -onChange=>function,
                        -onFocus=>function,
                        -onBlur=>function,
                        -onSelect=>function);
-override=>1
Text field should not inherit its value from a previous invocation of the script.

-onChange=>function
Browser should execute function when the user changes the text field.

-onFocus=>function
Browser should execute function when the focus is on the text field.

-onBlur=>function
Browser should execute function when the focus leaves the text field.

-onSelect=>function
Browser should execute function when the user changes a selected portion of the text field.

url

url = $query->url

Returns a URL of the current script without query information.

use_named_parameters

use_named_parameters( )

Specifies that functions should take named parameters.

user_agent

$query->user_agent( [string] )

Returns the value of the HTTP_USER_AGENT header.

string
If specified, only returns headers matching the specified string.