CGI
view release on metacpan or search on metacpan
lib/CGI/HTML/Functions.pod view on Meta::CPAN
action: this script
enctype: application/x-www-form-urlencoded for non-XHTML
multipart/form-data for XHTML, see multipart/form-data below.
end_form() returns the closing </form> tag.
start_form()'s enctype argument tells the browser how to package the various
fields of the form before sending the form to the server. Two
values are possible:
=over 4
=item B<application/x-www-form-urlencoded>
This is the older type of encoding. It is compatible with many CGI scripts and is
suitable for short fields containing text data. For your
convenience, CGI.pm stores the name of this encoding
type in B<&CGI::URL_ENCODED>.
=item B<multipart/form-data>
This is the newer type of encoding.
It is suitable for forms that contain very large fields or that
are intended for transferring binary data. Most importantly,
it enables the "file upload" feature. For
your convenience, CGI.pm stores the name of this encoding type
in B<&CGI::MULTIPART>
Forms that use this type of encoding are not easily interpreted
by CGI scripts unless they use CGI.pm or another library designed
to handle them.
If XHTML is activated (the default), then forms will be automatically
created using this type of encoding.
=back
The start_form() method uses the older form of encoding by
default unless XHTML is requested. If you want to use the
newer form of encoding by default, you can call
B<start_multipart_form()> instead of B<start_form()>. The
method B<end_multipart_form()> is an alias to B<end_form()>.
JAVASCRIPTING: The B<-name> and B<-onSubmit> parameters are provided
for use with JavaScript. The -name parameter gives the
form a name so that it can be identified and manipulated by
JavaScript functions. -onSubmit should point to a JavaScript
function that will be executed just before the form is submitted to your
server. You can use this opportunity to check the contents of the form
for consistency and completeness. If you find something wrong, you
can put up an alert box or maybe fix things up yourself. You can
abort the submission by returning false from this function.
Usually the bulk of JavaScript functions are defined in a <script>
block in the HTML header and -onSubmit points to one of these function
call. See start_html() for details.
=head2 Form elements
After starting a form, you will typically create one or more
textfields, popup menus, radio groups and other form elements. Each
of these elements takes a standard set of named arguments. Some
elements also have optional arguments. The standard arguments are as
follows:
=over 4
=item B<-name>
The name of the field. After submission this name can be used to
retrieve the field's value using the param() method.
=item B<-value>, B<-values>
The initial value of the field which will be returned to the script
after form submission. Some form elements, such as text fields, take
a single scalar -value argument. Others, such as popup menus, take a
reference to an array of values. The two arguments are synonyms.
=item B<-tabindex>
A numeric value that sets the order in which the form element receives
focus when the user presses the tab key. Elements with lower values
receive focus first.
=item B<-id>
A string identifier that can be used to identify this element to
JavaScript and DHTML.
=item B<-override>
A boolean, which, if true, forces the element to take on the value
specified by B<-value>, overriding the sticky behavior described
earlier for the B<-nosticky> pragma.
=item B<-onChange>, B<-onFocus>, B<-onBlur>, B<-onMouseOver>, B<-onMouseOut>, B<-onSelect>
These are used to assign JavaScript event handlers. See the
JavaScripting section for more details.
=back
Other common arguments are described in the next section. In addition
to these, all attributes described in the HTML specifications are
supported.
=head2 Creating a text field
print textfield(-name=>'field_name',
-value=>'starting value',
-size=>50,
-maxlength=>80);
-or-
print textfield('field_name','starting value',50,80);
textfield() will return a text input field.
B<Parameters>
=over 4
=item 1.
The first parameter is the required name for the field (-name).
=item 2.
The optional second parameter is the default starting value for the field
contents (-value, formerly known as -default).
=item 3.
The optional third parameter is the size of the field in
characters (-size).
lib/CGI/HTML/Functions.pod view on Meta::CPAN
-maxlength=>80);
-or-
print 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.
=head2 Creating a file upload field
print filefield(-name=>'uploaded_file',
-default=>'starting value',
-size=>50,
-maxlength=>80);
-or-
print filefield('uploaded_file','starting value',50,80);
filefield() will return a file upload field.
In order to take full advantage of this I<you must use the new
multipart encoding scheme> for the form. You can do this either
by calling B<start_form()> with an encoding type of B<&CGI::MULTIPART>,
or by calling the new method B<start_multipart_form()> instead of
vanilla B<start_form()>.
B<Parameters>
=over 4
=item 1.
The first parameter is the required name for the field (-name).
=item 2.
The optional second parameter is the starting value for the field contents
to be used as the default file name (-default).
For security reasons, browsers don't pay any attention to this field,
and so the starting value will always be blank. Worse, the field
loses its "sticky" behavior and forgets its previous contents. The
starting value field is called for in the HTML specification, however,
and possibly some browser will eventually provide support for it.
=item 3.
The optional third parameter is the size of the field in
characters (-size).
=item 4.
The optional fourth parameter is the maximum number of characters the
field will accept (-maxlength).
=back
JAVASCRIPTING: The B<-onChange>, B<-onFocus>, B<-onBlur>,
B<-onMouseOver>, B<-onMouseOut> and B<-onSelect> parameters are
recognized. See textfield() for details.
=head2 Creating a popup menu
print popup_menu('menu_name',
['eenie','meenie','minie'],
'meenie');
-or-
%labels = ('eenie'=>'your first choice',
'meenie'=>'your second choice',
'minie'=>'your third choice');
%attributes = ('eenie'=>{'class'=>'class of first choice'});
print popup_menu('menu_name',
['eenie','meenie','minie'],
'meenie',\%labels,\%attributes);
-or (named parameter style)-
print popup_menu(-name=>'menu_name',
-values=>['eenie','meenie','minie'],
-default=>['meenie','minie'],
-labels=>\%labels,
-attributes=>\%attributes);
popup_menu() creates a menu. Please note that the -multiple option will be
ignored if passed - use scrolling_list() if you want to create a menu that
supports multiple selections
=over 4
=item 1.
The required first argument is the menu's name (-name).
=item 2.
The required second argument (-values) is an array B<reference>
containing the list of menu items in the menu. You can pass the
method an anonymous array, as shown in the example, or a reference to
a named array, such as "\@foo".
=item 3.
The optional third parameter (-default) is the name of the default
menu choice. If not specified, the first item will be the default.
The values of the previous choice will be maintained across
queries. Pass an array reference to select multiple defaults.
=item 4.
The optional fourth parameter (-labels) is provided for people who
want to use different values for the user-visible label inside the
popup menu and the value returned to your script. It's a pointer to an
hash relating menu values to user-visible labels. If you
leave this parameter blank, the menu values will be displayed by
default. (You can also leave a label undefined if you want to).
=item 5.
The optional fifth parameter (-attributes) is provided to assign
any of the common HTML attributes to an individual menu item. It's
a pointer to a hash relating menu values to another
hash with the attribute's name as the key and the
attribute's value as the value.
=back
When the form is processed, the selected value of the popup menu can
be retrieved using:
$popup_menu_value = param('menu_name');
=head2 Creating an option group
Named parameter style
print popup_menu(-name=>'menu_name',
-values=>[qw/eenie meenie minie/,
optgroup(-name=>'optgroup_name',
-values => ['moe','catch'],
-attributes=>{'catch'=>{'class'=>'red'}})],
-labels=>{'eenie'=>'one',
'meenie'=>'two',
'minie'=>'three'},
-default=>'meenie');
Old style
print popup_menu('menu_name',
['eenie','meenie','minie',
optgroup('optgroup_name', ['moe', 'catch'],
{'catch'=>{'class'=>'red'}})],'meenie',
{'eenie'=>'one','meenie'=>'two','minie'=>'three'});
optgroup() creates an option group within a popup menu.
=over 4
=item 1.
The required first argument (B<-name>) is the label attribute of the
optgroup and is B<not> inserted in the parameter list of the query.
=item 2.
The required second argument (B<-values>) is an array reference
containing the list of menu items in the menu. You can pass the
method an anonymous array, as shown in the example, or a reference
to a named array, such as \@foo. If you pass a HASH reference,
the keys will be used for the menu values, and the values will be
used for the menu labels (see -labels below).
=item 3.
The optional third parameter (B<-labels>) allows you to pass a reference
to a hash containing user-visible labels for one or more
of the menu items. You can use this when you want the user to see one
menu string, but have the browser return your program a different one.
If you don't specify this, the value string will be used instead
("eenie", "meenie" and "minie" in this example). This is equivalent
to using a hash reference for the -values parameter.
=item 4.
An optional fourth parameter (B<-labeled>) can be set to a true value
and indicates that the values should be used as the label attribute
for each option element within the optgroup.
=item 5.
An optional fifth parameter (-novals) can be set to a true value and
indicates to suppress the val attribute in each option element within
the optgroup.
See the discussion on optgroup at W3C
(http://www.w3.org/TR/REC-html40/interact/forms.html#edef-OPTGROUP)
for details.
=item 6.
An optional sixth parameter (-attributes) is provided to assign
any of the common HTML attributes to an individual menu item. It's
a pointer to a hash relating menu values to another
hash with the attribute's name as the key and the
attribute's value as the value.
=back
=head2 Creating a scrolling list
print scrolling_list('list_name',
['eenie','meenie','minie','moe'],
['eenie','moe'],5,'true',{'moe'=>{'class'=>'red'}});
-or-
print scrolling_list('list_name',
['eenie','meenie','minie','moe'],
['eenie','moe'],5,'true',
\%labels,%attributes);
-or-
print scrolling_list(-name=>'list_name',
-values=>['eenie','meenie','minie','moe'],
-default=>['eenie','moe'],
-size=>5,
-multiple=>'true',
-labels=>\%labels,
-attributes=>\%attributes);
scrolling_list() creates a scrolling list.
B<Parameters:>
=over 4
=item 1.
The first and second arguments are the list name (-name) and values
(-values). As in the popup menu, the second argument should be an
array reference.
=item 2.
The optional third argument (-default) can be either a reference to a
list containing the values to be selected by default, or can be a
single value to select. If this argument is missing or undefined,
then nothing is selected when the list first appears. In the named
parameter version, you can use the synonym "-defaults" for this
parameter.
=item 3.
The optional fourth argument is the size of the list (-size).
=item 4.
The optional fifth argument can be set to true to allow multiple
simultaneous selections (-multiple). Otherwise only one selection
will be allowed at a time.
=item 5.
The optional sixth argument is a pointer to a hash
containing long user-visible labels for the list items (-labels).
If not provided, the values will be displayed.
=item 6.
The optional sixth parameter (-attributes) is provided to assign
any of the common HTML attributes to an individual menu item. It's
a pointer to a hash relating menu values to another
hash with the attribute's name as the key and the
attribute's value as the value.
When this form is processed, all selected list items will be returned as
a list under the parameter name 'list_name'. The values of the
selected items can be retrieved with:
@selected = param('list_name');
=back
=head2 Creating a group of related checkboxes
print checkbox_group(-name=>'group_name',
-values=>['eenie','meenie','minie','moe'],
-default=>['eenie','moe'],
-linebreak=>'true',
-disabled => ['moe'],
-labels=>\%labels,
-attributes=>\%attributes);
print checkbox_group('group_name',
['eenie','meenie','minie','moe'],
['eenie','moe'],'true',\%labels,
{'moe'=>{'class'=>'red'}});
HTML3-COMPATIBLE BROWSERS ONLY:
print checkbox_group(-name=>'group_name',
-values=>['eenie','meenie','minie','moe'],
-rows=2,-columns=>2);
checkbox_group() creates a list of checkboxes that are related
by the same name.
B<Parameters:>
=over 4
=item 1.
The first and second arguments are the checkbox name and values,
respectively (-name and -values). As in the popup menu, the second
argument should be an array reference. These values are used for the
user-readable labels printed next to the checkboxes as well as for the
values passed to your script in the query string.
=item 2.
The optional third argument (-default) can be either a reference to a
list containing the values to be checked by default, or can be a
single value to checked. If this argument is missing or undefined,
then nothing is selected when the list first appears.
=item 3.
The optional fourth argument (-linebreak) can be set to true to place
line breaks between the checkboxes so that they appear as a vertical
list. Otherwise, they will be strung together on a horizontal line.
=back
The optional B<-labels> argument is a pointer to a hash
relating the checkbox values to the user-visible labels that will be
printed next to them. If not provided, the values will be used as the
default.
The optional parameters B<-rows>, and B<-columns> cause
checkbox_group() to return an HTML3 compatible table containing the
checkbox group formatted with the specified number of rows and
columns. You can provide just the -columns parameter if you wish;
checkbox_group will calculate the correct number of rows for you.
The option B<-disabled> takes an array of checkbox values and disables
them by greying them out (this may not be supported by all browsers).
The optional B<-attributes> argument is provided to assign any of the
common HTML attributes to an individual menu item. It's a pointer to
a hash relating menu values to another hash
with the attribute's name as the key and the attribute's value as the
value.
The optional B<-tabindex> argument can be used to control the order in which
radio buttons receive focus when the user presses the tab button. If
passed a scalar numeric value, the first element in the group will
receive this tab index and subsequent elements will be incremented by
one. If given a reference to an array of radio button values, then
the indexes will be jiggered so that the order specified in the array
will correspond to the tab order. You can also pass a reference to a
hash in which the hash keys are the radio button values and the values
are the tab indexes of each button. Examples:
-tabindex => 100 # this group starts at index 100 and counts up
-tabindex => ['moe','minie','eenie','meenie'] # tab in this order
-tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order
The optional B<-labelattributes> argument will contain attributes
attached to the <label> element that surrounds each button.
When the form is processed, all checked boxes will be returned as
a list under the parameter name 'group_name'. The values of the
"on" checkboxes can be retrieved with:
( run in 1.085 second using v1.01-cache-2.11-cpan-364913b4093 )