NAME

SYNOPSIS

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

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

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

    $field->input_value('orange');
    print $field->internal_value; # 'orange'

    print $field->html_table(columns => 2);

    ...

DESCRIPTION

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.

HIERARCHY

See the "hierarchy" sections of the "HIERARCHY" in Rose::HTML::Form::Field and "HIERARCHY" in Rose::HTML::Form documentation for an overview of the relationship between field and form objects and the child-related methods inherited from Rose::HTML::Object.

HTML ATTRIBUTES

CONSTRUCTOR

new PARAMS

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

OBJECT METHODS

add_radio_button OPTION

Convenience alias for add_radio_buttons().

add_radio_buttons RADIO_BUTTONS

Adds radio buttons to the radio button group. RADIO_BUTTONS may take the following forms.

A reference to a hash of value/label pairs:

    $field->add_radio_buttons
    (
      {
        value1 => 'label1',
        value2 => 'label2',
        ...
      }
    );
    

An ordered list of value/label pairs:

    $field->add_radio_buttons
    (
      value1 => 'label1',
      value2 => 'label2',
      ...
    );
    

(Radio button 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_radio_buttons([ 'value1', 'value2', ... ]);
    

A list or reference to an array of Rose::HTML::Form::Field::RadioButton objects:

    $field->add_radio_buttons
    (
      Rose::HTML::Form::Field::RadioButton->new(...),
      Rose::HTML::Form::Field::RadioButton->new(...),
      ...
    );

    $field->add_radio_buttons
    (
      [
        Rose::HTML::Form::Field::RadioButton->new(...),
        Rose::HTML::Form::Field::RadioButton->new(...),
        ...
      ]
    );
    

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

    @args = 
    (
      # value/label pair
      value1 => 'label1',

      # value/hashref pair
      value2 =>
      {
        label => 'Some Label',
        id    => 'my_id',
        ...
      },

      # object
      Rose::HTML::Form::Field::RadioButton->new(...),

      ...
    );

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

All radio buttons are added to the end of the existing list of radio buttons.

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

choices [RADIO_BUTTONS]

This is an alias for the radio_buttons method.

columns [COLS]

Get or set the default number of columns to use in the output of the html_table() and xhtml_table() methods.

delete_items_html_attr NAME

This is an alias for the delete_radio_buttons_html_attr method.

delete_radio_button VALUE

Deletes the first radio button (according to the order that they are returned from radio_buttons()) whose "value" HTML attribute is VALUE. Returns the deleted radio button or undef if no such radio button exists.

delete_radio_buttons LIST

Repeatedly calls delete_radio_button, passing each value in LIST.

delete_radio_buttons_html_attr NAME

Delete the HTML attribute named NAME from each radio button.

has_value VALUE

Returns true if the radio button whose value is VALUE is selected, false otherwise.

hide_all_radio_buttons

Set hidden to true for all radio_buttons.

html

Returns the HTML for radio button group, which consists of the html() for each radio button object joined by html_linebreak() if linebreak() is true, or single spaces if it is false.

html_linebreak [HTML]

Get or set the HTML linebreak string. The default is "<br>\n"

html_table [ARGS]

Returns an HTML table containing the radio buttons. The table is constructed according ARGS, which are name/value pairs. Valid arguments are:

internal_value

The selected value is returned (or undef if no value is selected).

items_html_attr NAME [, VALUE]

This is an alias for the radio_buttons_html_attr method.

labels [LABELS]

Get or set the labels for all radio buttons. 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.

linebreak [BOOL]

Get or set the flag that determines whether or not the string stored in html_linebreak() or xhtml_linebreak() is used to separate radio buttons in the output of html() or xhtml(), respectively. Defaults to true.

radio_button VALUE

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

radio_buttons [RADIO_BUTTONS]

Get or set the full list of radio buttons in the group. RADIO_BUTTONS 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 Rose::HTML::Form::Field::RadioButton objects. Passing an odd number of items in the value/label argument list causes a fatal error. Radio button values and labels 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 radio buttons along with labels in the constructor, use both the radio_buttons() and labels() methods in the correct order. Example:

    $field = 
      Rose::HTML::Form::Field::RadioButtonGroup->new(
        name          => 'fruits',
        radio_buttons => [ '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 radio_buttons() 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 radio button group's Rose::HTML::Form::Field::RadioButton objects in list context, or a reference to an array of the same in scalar context. Hidden radio buttons will be included in this list. These are the actual objects used in the field. Modifying them will modify the field itself.

radio_buttons_html_attr NAME [, VALUE]

If VALUE is passed, set the HTML attribute named NAME on all radio buttons. Otherwise, return the value of the HTML attribute named NAME on the first radio button encountered in the list of all radio buttons.

rows [ROWS]

Get or set the default number of rows to use in the output of the html_table() and xhtml_table() methods.

show_all_radio_buttons

Set hidden to false for all radio_buttons.

value [VALUE]

Simply calls input_value(), passing all arguments.

value_label [VALUE [, LABEL]

If no arguments are passed, it returns the label of the selected radio button, or the value itself if it has no label. If no radio button is selected, undef is returned.

With arguments, it will get or set the label for the radio button whose value is VALUE. The label for that radio button is returned. If the radio button exists, but has no label, then the value itself is returned. If the radio button does not exist, then undef is returned.

xhtml

Returns the XHTML for radio button group, which consists of the xhtml() for each radio button object joined by xhtml_linebreak() if linebreak() is true, or single spaces if it is false.

xhtml_linebreak [XHTML]

Get or set the XHTML linebreak string. The default is "<br />\n"

xhtml_table

Equivalent to html_table() but using XHTML markup for each radio button.

AUTHOR

LICENSE