Rose::HTML::Form::Field::OptionGroup.3pm

Langue: en

Version: 2008-02-25 (mandriva - 01/05/08)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

Rose::HTML::Form::Field::OptionGroup - Object representation of a group of options in a pop-up menu or select box in an HTML form.

SYNOPSIS

     $field = 
       Rose::HTML::Form::Field::OptionGroup->new(
         name  => 'fruits',
         label => 'Fruits');
 
     $field->options(apple  => 'Apple',
                     orange => 'Orange',
                     grape  => 'Grape');
 
     print $field->html;
 
     ...

DESCRIPTION

Rose::HTML::Form::Field::OptionGroup is an object representation of a group of options in a pop-up menu or select box in an HTML form. Yes, this is the often-overlooked (and sometimes ill-supported) ``optgroup'' HTML tag.

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
     disabled
     id
     label
     lang
     name
     onblur
     onclick
     ondblclick
     onfocus
     onkeydown
     onkeypress
     onkeyup
     onmousedown
     onmousemove
     onmouseout
     onmouseover
     onmouseup
     style
     tabindex
     title
     value
     xml:lang

Required attributes:

     label

Boolean attributes:

     disabled

CONSTRUCTOR

new PARAMS
Constructs a new Rose::HTML::Form::Field::OptionGroup 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 option group. OPTIONS may be a reference to a hash of value/label pairs, a reference to an array of values, or a list of Rose::HTML::Form::Field::Option objects. 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 the keys of the hash according to the default behavior of Perl's built-in sort() function. Options are added to the end of the existing list of options.
choices [OPTIONS]
This is an alias for the options method.
has_value VALUE
Returns true if VALUE is selected in the option group, false otherwise.
label [VALUE]
Get or set the value of the ``label'' HTML attribute.
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 Rose::HTML::Form::Field::Option objects. 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 the keys of the hash 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::OptionGroup->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 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_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@gmail.com) Copyright (c) 2008 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.