NAME

Rose::HTML::Form::Field::CheckBoxGroup - A group of checkboxes in an HTML form.

SYNOPSIS

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

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

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

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

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

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

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

...

DESCRIPTION

Rose::HTML::Form::Field::CheckBoxGroup is an object wrapper for a group of checkboxes 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

None. This class is simply an aggregator of Rose::HTML::Form::Field::CheckBox objects.

CONSTRUCTOR

new PARAMS

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

OBJECT METHODS

add_checkbox OPTION

Convenience alias for add_checkboxes().

add_checkboxes CHECKBOXES

Adds checkboxes to the checkbox group. CHECKBOXES 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::CheckBox objects. Passing an odd number of items in the value/label argument list causes a fatal error. Checkbox values and labels passed as a hash reference are sorted by value according to the default behavior of Perl's built-in sort() function. Checkboxes are added to the end of the existing list of checkboxes.

add_value VALUE

Put a check in the checkbox whose value is VALUE.

add_values VALUE1, VALUE2, ...

Put a check in the checkboxes whose values are equal to VALUE1, VALUE2, etc.

checkbox VALUE

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

checkboxes CHECKBOXES

Get or set the full list of checkboxes in the group. CHECKBOXES 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::CheckBox objects. Passing an odd number of items in the value/label argument list causes a fatal error. Checkbox 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 checkboxes along with labels in the constructor, use both the checkboxes() and labels() methods in the correct order. Example:

$field = 
  Rose::HTML::Form::Field::CheckBoxGroup->new(
    name       => 'fruits',
    checkboxes => [ '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 checkboxes() 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 checkbox group's Rose::HTML::Form::Field::CheckBox 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.

columns [COLS]

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

has_value VALUE

Returns true if the checkbox whose value is VALUE is checked, false otherwise.

html

Returns the HTML for checkbox group, which consists of the html() for each checkbox 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 checkboxes. The table is constructed according ARGS, which are name/value pairs. Valid arguments are:

cellpadding

The value of the "table" tag's "cellpadding" HTML attribute. Defaults to 2.

cellspacing

The value of the "table" tag's "cellspacing" HTML attribute. Defaults to 0.

columns

The number of columns in the table. Defaults to columns(), or 1 if columns() is false.

format_item

The name of the method to call on each checkbox object in order to fill each table cell. Defaults to "html"

rows

The number of rows in the table. Defaults to rows(), or 1 if rows() is false.

table

A reference to a hash of HTML attribute/value pairs to be used in the "table" tag. Some attribute values be overridden by the equivalent standalone arguments (e.g., cellpadding and cellspacing).

td

A reference to a hash of HTML attribute/value pairs to be used in the "td" tag, or an array of such hashes to be used in order for the table cells of each row. If the array contains fewer entries than the number of cells in each row of the table, then the last entry is used for all of the remaining cells in the row. Defaults to a reference to an empty hash, {}.

tr

A reference to a hash of HTML attribute/value pairs to be used in the "tr" tag, or an array of such hashes to be used in order for the table rows. If the array contains fewer entries than the number of rows in the table, then the last entry is used for all of the remaining rows. Defaults to { valign => 'top' }.

Specifying "rows" and "columns" values (either as ARGS or via rows() and columns()) that are both greater than 1 leads to undefined behavior if there are not exactly "rows x columns" checkboxes. For predictable behavior, set either rows or columns to a value greater than 1, but not both.

To remove HTML attributes that have default values, simply pass undef as the value for those attributes. Example:

print $field->html_table();    

# <table cellpadding="2" cellspacing="0">
# <tr valign="top">
# <td>...

print $field->html_table(table => undef, tr => undef);

# <table>
# <tr>
# <td>...

label VALUE [, LABEL]

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

labels [LABELS]

Get or set the labels for all checkboxes. 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 checkboxes in the output of html() or xhtml(), respectively. Defaults to true.

rows [ROWS]

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

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 checkbox (according to the order that they are returned by internal_value()), or the value itself if it has no label. If no checkbox 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 checkboxes. If a checkbox has no label, the checkbox value is substituted. If no checkboxes are selected, then an empty array (in list context) or reference to an empty array (in scalar context) is returned.

xhtml

Returns the XHTML for checkbox group, which consists of the xhtml() for each checkbox 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().

AUTHOR

John C. Siracusa (siracusa@mindspring.com)