Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Rose::HTML::Form::Field::SelectBox
Object representation of a select box in an HTML form.

Rose::HTML::Form::Field::SelectBox - Object representation of a select box in an HTML form.


NAME

Rose::HTML::Form::Field::SelectBox - Object representation of a select box in an HTML form.


SYNOPSIS


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

    $field->options(apple  => 'Apple',

                    orange => 'Orange',

                    grape  => 'Grape');

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

    $field->input_value('orange');

    print $field->internal_value; # 'orange'

    $field->multiple(1);

    $field->add_value('grape');

    print join(',', $field->internal_value); # 'grape,orange'

    $field->has_value('grape'); # true

    $field->has_value('apple'); # false

    print $field->html;

    ...


DESCRIPTION

the Rose::HTML::Form::Field::SelectBox manpage is an object representation of a select box field in an HTML form.

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


HTML ATTRIBUTES

Valid attributes:


    accesskey

    class

    dir

    disabled

    id

    lang

    multiple

    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

Boolean attributes:


    disabled

    multiple


CONSTRUCTOR

new PARAMS
Constructs a new the Rose::HTML::Form::Field::SelectBox manpage 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 select box. OPTIONS may take the following forms.

A reference to a hash of value/label pairs:


    $field->add_options

    (

      {

        value1 => 'label1',

        value2 => 'label2',

        ...

      }

    );

An ordered list of value/label pairs:


    $field->add_options

    (

      value1 => 'label1',

      value2 => 'label2',

      ...

    );

(Option values and labels passed as a hash reference are sorted by value according to the default behavior of Perl's built-in sort() function.)

A reference to an array of containing only plain scalar values:


    $field->add_options([ 'value1', 'value2', ... ]);

A list or reference to an array of the Rose::HTML::Form::Field::Option manpage or the Rose::HTML::Form::Field::OptionGroup manpage objects:


    $field->add_options

    (

      Rose::HTML::Form::Field::Option->new(...),

      Rose::HTML::Form::Field::OptionGroup->new(...),

      Rose::HTML::Form::Field::Option->new(...),

      ...

    );

    $field->add_options

    (

      [

      Rose::HTML::Form::Field::Option->new(...),

      Rose::HTML::Form::Field::OptionGroup->new(...),

      Rose::HTML::Form::Field::Option->new(...),

        ...

      ]

    );

A list or reference to an array containing a mix of value/label pairs, value/hashref pairs, and the Rose::HTML::Form::Field::Option manpage or the Rose::HTML::Form::Field::OptionGroup manpage objects:


    @args = 

    (

      # value/label pair

      value1 => 'label1',

      # option group object

      Rose::HTML::Form::Field::OptionGroup->new(...),

      # value/hashref pair

      value2 =>

      {

        label => 'Some Label',

        id    => 'my_id',

        ...

      },

      # option object

      Rose::HTML::Form::Field::Option->new(...),

      ...

    );

    $field->add_options(@args);  # list

    $field->add_options(\@args); # reference to an array

Please note: the second form (passing a reference to an array) requires that at least one item in the referenced array is not a plain scalar, lest it be confused with ``a reference to an array of containing only plain scalar values.''

All options are added to the end of the existing list of options.

Option groups may also be added by nesting another level of array references. For example, this:


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

    $field->options(apple  => 'Apple',

                    orange => 'Orange',

                    grape  => 'Grape');

    $group = Rose::HTML::Form::Field::OptionGroup->new(label => 'Others');

    $group->options(juji  => 'Juji',

                    peach => 'Peach');

    $field->add_options($group);

is equivalent to this:


    $field = 

      Rose::HTML::Form::Field::SelectBox->new(

        name    => 'fruits',

        options =>

        [

          apple  => 'Apple',

          orange => 'Orange',

          grape  => 'Grape',

          Others =>

          [

            juji  => { label => 'Juji' },

            peach => { label => 'Peach' },

          ],

        ]);

    $field->add_options($group);

add_value VALUE
Add VALUE to the list of selected values.

add_values VALUE1, VALUE2, ...
Add multiple values to the list of selected values.

choices [OPTIONS]
This is an alias for the options method.

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

delete_options LIST
Repeatedly calls delete_option, passing each value in LIST as an arugment.

delete_option_group LABEL
Deletes the first option group (according to the order that they are returned from options()) whose ``label'' HTML attribute is LABEL. Returns the deleted option group or undef if no such option exists.

delete_option_groups LIST
Repeatedly calls delete_option_group, passing each value in LIST.

has_value VALUE
Returns true if VALUE is selected in the select box, false otherwise.

hide_all_options
Set hidden to true for all options.

internal_value
If multiple is true, a reference to an array of selected values is returned in scalar context, and a list of selected values is returned in list context. Otherwise, the selected value is returned (or undef if no value is selected).

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.

multiple [BOOL]
This is just an accessor method for the ``multiple'' boolean HTML attribute, but I'm documenting it here so that I can warn that trying to select multiple values in a non-multiple-valued select box will cause a fatal error.

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 select box. OPTIONS may be a reference to a hash of value/label pairs, an ordered list of value/label pairs, a reference to an array of values, or a list of objects that are of, or inherit from, the classes the Rose::HTML::Form::Field::Option manpage or the Rose::HTML::Form::Field::OptionGroup manpage. 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::SelectBox->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 the Rose::Object manpage 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 select box's the Rose::HTML::Form::Field::Option manpage and/or the Rose::HTML::Form::Field::OptionGroup manpage objects in list context, or a reference to an array of the same in scalar context. Hidden options will be included in this list. These are the actual objects used in the field. Modifying them will modify the field itself.

option_group LABEL
Returns the the Rose::HTML::Form::Field::OptionGroup manpage object whose ``label'' HTML attribute is LABEL, or undef if no such option group exists.

show_all_options
Set hidden to false for all options.

value [VALUE]
Simply calls input_value(), passing all arguments.

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

value_labels
Returns an array (in list context) or reference to an array (in scalar context) of the labels of the selected values. If a value has no label, the value itself is substituted. If no values are selected, then an empty array (in list context) or reference to an empty array (in scalar context) is returned.


AUTHOR

John C. Siracusa (siracusa@gmail.com)


COPYRIGHT

Copyright (c) 2007 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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy