CGI.pm Reference (Perl in a Nutshell, 2nd Edition)

10.7. CGI.pm Reference

The following methods are supported by CGI.pm.

$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 append.
-values=>'value': The value to append. Multiple values can be specified as a reference to an anonymous array.

auth_type

auth_type(  )

Returns the authorization method.

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 will be 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 will be retrieved rather than defined.

-expires=>expcode

Specifies an expiration timestamp (such as +3d for three 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

Expires 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

Use this cookie only 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, prints 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

Specifies the content type.

-nph=>1

Uses headers for a no-parse-header script.

-status=>status_code

Specifies the status code.

-expires=>expcode

Specifies an expiration timestamp (such as +3d for three 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

Expires immediately

-cookie=>cookie

Specifies a cookie. The cookie may be a scalar value or an array reference.

-header=>value

Specifies any HTTP header.

-target=>frame

Writes 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,yposition is returned as name.xand 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 that will 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 that will 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 popup 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 example below).
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 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': Inserts 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 will be 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 backwards 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': Allows 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 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

Copyright for this document description

description

Description for this document

attribute=>'value'

Specifies an attribute to the <BODY> tag
-script=>'$script': Specifies a JavaScript script to be embedded within a <SCRIPT> block.
-onLoad=>'$function': Browser should execute specified function upon entering page.
-onUnload=>'$function': Browser should execute specified function upon leaving 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 on the image

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 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, returns only headers matching the specified string

user_name

user_name(  )

Returns the remote user's login name; unreliable.