NAME

Rose::HTML::Form::Field::PopUpMenu - Object representation of a pop-up menu in an HTML form.

SYNOPSIS

$field = Rose::HTML::Form::Field::PopUpMenu->new(name => 'fruits');

$field->options(apple  => 'Apple',
                orange => 'Orange',
                grape  => 'Grape');

print $field->label('apple'); # 'Apple'

$field->input_value('orange');

print $field->internal_value; # 'orange'

print $field->html;

...

DESCRIPTION

Rose::HTML::Form::Field::PopUpMenu is an object representation of a pop-up menu field in an HTML form.

This class inherits from, and follows the conventions of, Rose::HTML::Form::Field. Inherited methods that are not overridden will not be documented a second time here. See the Rose::HTML::Form::Field documentation for more information.

HTML ATTRIBUTES

Valid attributes:

accesskey
class
dir
id
lang
name
onblur
onchange
onclick
ondblclick
onfocus
onkeydown
onkeypress
onkeyup
onmousedown
onmousemove
onmouseout
onmouseover
onmouseup
size
style
tabindex
title
value
xml:lang

Required attributes:

name
size

CONSTRUCTOR

new PARAMS

Constructs a new Rose::HTML::Form::Field::PopUpMenu object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.

OBJECT METHODS

add_option OPTION

Convenience alias for add_options().

add_options OPTIONS

Adds options to the pop-up menu. OPTIONS may be a reference to a hash of value/label pairs, a reference to an array of values, or a list of objects that are of, or inherit from, the classes Rose::HTML::Form::Field::Option or Rose::HTML::Form::Field::OptionGroup. Passing an odd number of items in the value/label argument list causes a fatal error. Options passed as a hash reference are sorted by value according to the default behavior of Perl's built-in sort() function. Options are added to the end of the existing list of options.

has_value VALUE

Returns true if VALUE is selected in the pop-up menu, false otherwise.

label VALUE [, LABEL]

Get or set the label for a single value. The label for VALUE is returned. If the value exists, but has no label, then the value itself is returned. If the value does not exist, then undef is returned.

labels [LABELS]

Get or set the labels for all values. If LABELS is a reference to a hash or a list of value/label pairs, then LABELS replaces all existing labels. Passing an odd number of items in the list version of LABELS causes a fatal error.

Returns a hash of value/label pairs in list context, or a reference to a hash in scalar context.

option VALUE

Returns the first option (according to the order that they are returned from options()) whose "value" HTML attribute is VALUE, or undef if no such option exists.

options OPTIONS

Get or set the full list of options in the pop-up menu. OPTIONS may be a reference to a hash of value/label pairs, a reference to an array of values, or a list of objects that are of, or inherit from, the classes Rose::HTML::Form::Field::Option or Rose::HTML::Form::Field::OptionGroup. Passing an odd number of items in the value/label argument list causes a fatal error. Options passed as a hash reference are sorted by value according to the default behavior of Perl's built-in sort() function.

To set an ordered list of option values along with labels in the constructor, use both the options() and labels() methods in the correct order. Example:

$field = 
  Rose::HTML::Form::Field::PopUpMenu->new(
    name    => 'fruits',
    options => [ 'apple', 'pear' ],
    labels  => { apple => 'Apple', pear => 'Pear' });

Remember that methods are called in the order that they appear in the constructor arguments (see the Rose::Object documentation), so options() will be called before labels() in the example above. This is important; it will not work in the opposite order.

Returns a list of the pop-up menu's Rose::HTML::Form::Field::Option and/or Rose::HTML::Form::Field::OptionGroup objects in list context, or a reference to an array of the same in scalar context. These are the actual objects used in the field. Modifying them will modify the field itself.

value [VALUE]

Simply calls input_value(), passing all arguments.

value_label

Returns the label of the first selected value (according to the order that they are returned by internal_value()), or the value itself if it has no label. If no value is selected, undef is returned.

AUTHOR

John C. Siracusa (siracusa@mindspring.com)