• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL
Help

Chapter 14. The CGI.pm Module > CGI.pm Reference

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.

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 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 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 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.

user_name

user_name()

Returns the remote user's login name; unreliable.


PREVIEW

                                                                          

Not a subscriber?

Start A Free Trial


  
  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint