File Coverage

blib/lib/Rose/HTML/Form/Field/CheckboxGroup.pm
Criterion Covered Total %
statement 25 27 92.5
branch 7 8 87.5
condition 2 4 50.0
subroutine 8 10 80.0
pod 2 2 100.0
total 44 51 86.2


line stmt bran cond sub pod time code
1             package Rose::HTML::Form::Field::CheckboxGroup;
2              
3 5     5   4650 use strict;
  5         12  
  5         156  
4              
5 5     5   28 use Carp;
  5         11  
  5         290  
6              
7 5     5   29 use base 'Rose::HTML::Form::Field::Group::OnOff';
  5         12  
  5         1438  
8              
9 5     5   35 use Rose::HTML::Form::Field::Group;
  5         12  
  5         32  
10 5     5   1290 use Rose::HTML::Form::Field::Checkbox;
  5         17  
  5         35  
11              
12             our $VERSION = '0.606';
13              
14 14     14   74 sub _item_class { shift->object_type_class_loaded('checkbox') }
15 0     0   0 sub _item_name { 'checkbox' }
16 0     0   0 sub _item_name_plural { 'checkboxes' }
17              
18             *checkboxes = \&Rose::HTML::Form::Field::Group::items;
19             *visible_checkboxes = \&Rose::HTML::Form::Field::Group::visible_items;
20              
21             *checkbox = \&Rose::HTML::Form::Field::Group::OnOff::item;
22             *add_checkboxes = \&Rose::HTML::Form::Field::Group::add_items;
23             *add_checkbox = \&add_checkboxes;
24              
25             *choices = \&checkboxes;
26              
27             *show_all_checkboxes = \&Rose::HTML::Form::Field::Group::show_all_items;
28             *hide_all_checkboxes = \&Rose::HTML::Form::Field::Group::hide_all_items;
29              
30             *delete_checkbox = \&Rose::HTML::Form::Field::Group::delete_item;
31             *delete_checkboxes = \&Rose::HTML::Form::Field::Group::delete_items;
32              
33             *delete_checkbox_group = \&Rose::HTML::Form::Field::Group::delete_item_group;
34             *delete_checkboxes_groups = \&Rose::HTML::Form::Field::Group::delete_item_groups;
35              
36             *checkboxes_html_attr = \&Rose::HTML::Form::Field::Group::items_html_attr;
37             *delete_checkboxes_html_attr = \&Rose::HTML::Form::Field::Group::delete_items_html_attr;
38              
39             sub html_table
40             {
41 4     4 1 17 my($self, %args) = @_;
42              
43 4 100       20 $args{'class'} = defined $args{'class'} ?
44             "$args{'class'} checkbox-group" : 'checkbox-group';
45              
46             #$args{'cellpadding'} = 2 unless(exists $args{'cellpadding'});
47             #$args{'cellspacing'} = 0 unless(exists $args{'cellspacing'});
48             #$args{'tr'} = { valign => 'top' } unless(exists $args{'tr'});
49              
50 4   50     26 $args{'tr'} ||= {};
51 4   50     24 $args{'td'} ||= {};
52              
53             $args{'table'}{'class'} = defined $args{'table'}{'class'} ?
54             "$args{'table'}{'class'} checkbox-group" :
55 4 50       24 defined $args{'class'} ? $args{'class'} : undef;
    100          
56              
57             #$args{'table'}{'cellpadding'} = $args{'cellpadding'}
58             # unless((exists $args{'table'} && !defined $args{'table'}) ||
59             # exists $args{'table'}{'cellpadding'});
60              
61             #$args{'table'}{'cellspacing'} = $args{'cellspacing'}
62             # unless((exists $args{'table'} && !defined $args{'table'}) ||
63             # exists $args{'table'}{'cellspacing'});
64              
65 4 100       13 if($args{'_xhtml'})
66             {
67             return
68 1         6 $self->SUPER::html_table(items => scalar $self->visible_checkboxes,
69             format_item => \&Rose::HTML::Form::Field::Group::_xhtml_item,
70             %args);
71             }
72             else
73             {
74             return
75 3         15 $self->SUPER::html_table(items => scalar $self->visible_checkboxes,
76             format_item => \&Rose::HTML::Form::Field::Group::_html_item,
77             %args);
78             }
79             }
80              
81 1     1 1 8 sub xhtml_table { shift->html_table(@_, _xhtml => 1) }
82              
83             1;
84              
85             __END__
86              
87             =head1 NAME
88              
89             Rose::HTML::Form::Field::CheckboxGroup - A group of checkboxes in an HTML form.
90              
91             =head1 SYNOPSIS
92              
93             $field =
94             Rose::HTML::Form::Field::CheckboxGroup->new(name => 'fruits');
95              
96             $field->checkboxes(apple => 'Apple',
97             orange => 'Orange',
98             grape => 'Grape');
99              
100             print $field->value_label('apple'); # 'Apple'
101              
102             $field->input_value('orange');
103             print $field->internal_value; # 'orange'
104              
105             $field->add_value('grape');
106             print join(',', $field->internal_value); # 'grape,orange'
107              
108             $field->has_value('grape'); # true
109             $field->has_value('apple'); # false
110              
111             print $field->html_table(columns => 2);
112              
113             ...
114              
115             =head1 DESCRIPTION
116              
117             L<Rose::HTML::Form::Field::CheckboxGroup> is an object wrapper for a group of checkboxes in an HTML form.
118              
119             This class inherits from, and follows the conventions of, L<Rose::HTML::Form::Field>. Inherited methods that are not overridden will not be documented a second time here. See the L<Rose::HTML::Form::Field> documentation for more information.
120              
121             =head1 HIERARCHY
122              
123             A checkbox group is an abstraction with no corresponding parent HTML element; the individual L<checkbox|Rose::HTML::Form::Field::Checkbox> objects in the group exist as siblings. As such, the list of L<child|Rose::HTML::Object/HIERARCHY> objects will always be empty and cannot be modified. To get the list of siblings, use the L<checkboxes|/checkboxes> method.
124              
125             See the "hierarchy" sections of the L<Rose::HTML::Form::Field/HIERARCHY> and L<Rose::HTML::Form/HIERARCHY> documentation for an overview of the relationship between field and form objects and the child-related methods inherited from L<Rose::HTML::Object>.
126              
127             =head1 HTML ATTRIBUTES
128              
129             None. This class is simply an aggregator of L<Rose::HTML::Form::Field::Checkbox> objects.
130              
131             =head1 CONSTRUCTOR
132              
133             =over 4
134              
135             =item B<new PARAMS>
136              
137             Constructs a new L<Rose::HTML::Form::Field::CheckboxGroup> object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.
138              
139             =back
140              
141             =head1 OBJECT METHODS
142              
143             =over 4
144              
145             =item B<add_checkbox OPTION>
146              
147             Convenience alias for L<add_checkboxes()|/add_checkboxes>.
148              
149             =item B<add_checkboxes CHECKBOXES>
150              
151             Adds checkboxes to the checkbox group. CHECKBOXES may take the following forms.
152              
153             A reference to a hash of value/label pairs:
154              
155             $field->add_checkboxes
156             (
157             {
158             value1 => 'label1',
159             value2 => 'label2',
160             ...
161             }
162             );
163              
164             An ordered list of value/label pairs:
165              
166             $field->add_checkboxes
167             (
168             value1 => 'label1',
169             value2 => 'label2',
170             ...
171             );
172              
173             (Checkbox values and labels passed as a hash reference are sorted by value according to the default behavior of Perl's built-in L<sort()|perlfunc/sort> function.)
174              
175             A reference to an array of containing B<only> plain scalar values:
176              
177             $field->add_checkboxes([ 'value1', 'value2', ... ]);
178              
179             A list or reference to an array of L<Rose::HTML::Form::Field::Checkbox> objects:
180              
181             $field->add_checkboxes
182             (
183             Rose::HTML::Form::Field::Checkbox->new(...),
184             Rose::HTML::Form::Field::Checkbox->new(...),
185             ...
186             );
187              
188             $field->add_checkboxes
189             (
190             [
191             Rose::HTML::Form::Field::Checkbox->new(...),
192             Rose::HTML::Form::Field::Checkbox->new(...),
193             ...
194             ]
195             );
196              
197             A list or reference to an array containing a mix of value/label pairs, value/hashref pairs, and L<Rose::HTML::Form::Field::Checkbox> objects:
198              
199             @args =
200             (
201             # value/label pair
202             value1 => 'label1',
203              
204             # value/hashref pair
205             value2 =>
206             {
207             label => 'Some Label',
208             id => 'my_id',
209             ...
210             },
211              
212             # object
213             Rose::HTML::Form::Field::Checkbox->new(...),
214              
215             ...
216             );
217              
218             $field->add_checkboxes(@args); # list
219             $field->add_checkboxes(\@args); # reference to an array
220              
221             B<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."
222              
223             All checkboxes are added to the end of the existing list of checkboxes.
224              
225             =item B<add_value VALUE>
226              
227             Put a check in the checkbox whose value is VALUE.
228              
229             =item B<add_values VALUE1, VALUE2, ...>
230              
231             Put a check in the checkboxes whose values are equal to VALUE1, VALUE2, etc.
232              
233             =item B<checkbox VALUE>
234              
235             Returns the first checkbox (according to the order that they are returned from L<checkboxes()|/checkboxes>) whose "value" HTML attribute is VALUE, or undef if no such checkbox exists.
236              
237             =item B<checkboxes [CHECKBOXES]>
238              
239             Get or set the full list of checkboxes in the group. CHECKBOXES 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 L<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 L<sort()|perlfunc/sort> function.
240              
241             To set an ordered list of checkboxes along with labels in the constructor, use both the L<checkboxes()|/checkboxes> and L<labels()|/labels> methods in the correct order. Example:
242              
243             $field =
244             Rose::HTML::Form::Field::CheckboxGroup->new(
245             name => 'fruits',
246             checkboxes => [ 'apple', 'pear' ],
247             labels => { apple => 'Apple', pear => 'Pear' });
248              
249             Remember that methods are called in the order that they appear in the constructor arguments (see the L<Rose::Object> documentation), so L<checkboxes()|/checkboxes> will be called before L<labels()|/labels> in the example above. This is important; it will not work in the opposite order.
250              
251             Returns a list of the checkbox group's L<Rose::HTML::Form::Field::Checkbox> objects in list context, or a reference to an array of the same in scalar context. L<Hidden|Rose::HTML::Form::Field::Checkbox/hidden> checkboxes I<will> be included in this list. These are the actual objects used in the field. Modifying them will modify the field itself.
252              
253             =item B<choices [CHECKBOXES]>
254              
255             This is an alias for the L<checkboxes|/checkboxes> method.
256              
257             =item B<columns [COLS]>
258              
259             Get or set the default number of columns to use in the output of the L<html_table()|/html_table> and L<xhtml_table()|/xhtml_table> methods.
260              
261             =item B<checkboxes_html_attr NAME [, VALUE]>
262              
263             If VALUE is passed, set the L<HTML attribute|Rose::HTML::Object/html_attr> named NAME on all L<checkboxes|/checkboxes>. Otherwise, return the value of the L<HTML attribute|Rose::HTML::Object/html_attr> named NAME on the first checkbox encountered in the list of all L<checkboxes|/checkboxes>.
264              
265             =item B<delete_checkbox VALUE>
266              
267             Deletes the first checkbox (according to the order that they are returned from L<checkboxes()|/checkboxes>) whose "value" HTML attribute is VALUE. Returns the deleted checkbox or undef if no such checkbox exists.
268              
269             =item B<delete_checkboxes LIST>
270              
271             Repeatedly calls L<delete_checkbox|/delete_checkbox>, passing each value in LIST.
272              
273             Deletes the first checkbox (according to the order that they are returned from L<checkboxes()|/checkboxes>) whose "value" HTML attribute is VALUE, or undef if no such checkbox exists.
274              
275             =item B<delete_checkboxes_html_attr NAME>
276              
277             Delete the L<HTML attribute|Rose::HTML::Object/html_attr> named NAME from each L<checkbox|/checkboxes>.
278              
279             =item B<delete_items_html_attr NAME>
280              
281             This is an alias for the L<delete_checkboxes_html_attr|/delete_checkboxes_html_attr> method.
282              
283             =item B<has_value VALUE>
284              
285             Returns true if the checkbox whose value is VALUE is checked, false otherwise.
286              
287             =item B<hide_all_checkboxes>
288              
289             Set L<hidden|Rose::HTML::Form::Field::Checkbox/hidden> to true for all L<checkboxes|/checkboxes>.
290              
291             =item B<html>
292              
293             Returns the HTML for checkbox group, which consists of the L<html()|/html> for each checkbox object joined by L<html_linebreak()|/html_linebreak> if L<linebreak()|/linebreak> is true, or single spaces if it is false.
294              
295             =item B<html_linebreak [HTML]>
296              
297             Get or set the HTML linebreak string. The default is "E<lt>brE<gt>\n"
298              
299             =item B<html_table [ARGS]>
300              
301             Returns an HTML table containing the checkboxes. The table is constructed according ARGS, which are name/value pairs. Valid arguments are:
302              
303             =over 4
304              
305             =item class
306              
307             The value of the "table" tag's "class" HTML attribute. Defaults to C<checkbox-group>. Any value passed for this attribute joined to C<checkbox-group> with a single space.
308              
309             =item columns
310              
311             The number of columns in the table. Defaults to L<columns()|/columns>, or 1 if L<columns()|/columns> is false.
312              
313             =item format_item
314              
315             The name of the method to call on each checkbox object in order to fill each table cell. Defaults to "html"
316              
317             =item rows
318              
319             The number of rows in the table. Defaults to L<rows()|/rows>, or 1 if L<rows()|/rows> is false.
320              
321             =item table
322              
323             A reference to a hash of HTML attribute/value pairs to be used in the "table" tag.
324              
325             =item td
326              
327             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, C<{}>.
328              
329             =item tr
330              
331             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 a reference to an empty hash, C<{}>.
332              
333             =back
334              
335             Specifying "rows" and "columns" values (either as ARGS or via L<rows()|/rows> and L<columns()|/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.
336              
337             =item B<items_html_attr NAME [, VALUE]>
338              
339             This is an alias for the L<checkboxes_html_attr|/checkboxes_html_attr> method.
340              
341             =item B<label VALUE [, LABEL]>
342              
343             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.
344              
345             =item B<labels [LABELS]>
346              
347             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.
348              
349             Returns a hash of value/label pairs in list context, or a reference to a hash in scalar context.
350              
351             =item B<linebreak [BOOL]>
352              
353             Get or set the flag that determines whether or not the string stored in L<html_linebreak()|/html_linebreak> or L<xhtml_linebreak()|/xhtml_linebreak> is used to separate checkboxes in the output of L<html()|/html> or L<xhtml()|/xhtml>, respectively. Defaults to true.
354              
355             =item B<rows [ROWS]>
356              
357             Get or set the default number of rows to use in the output of the L<html_table()|/html_table> and L<xhtml_table()|/xhtml_table> methods.
358              
359             =item B<show_all_checkboxes>
360              
361             Set L<hidden|Rose::HTML::Form::Field::Checkbox/hidden> to false for all L<checkboxes|/checkboxes>.
362              
363             =item B<value [VALUE]>
364              
365             Simply calls L<input_value()|Rose::HTML::Form::Field/input_value>, passing all arguments.
366              
367             =item B<values [VALUE]>
368              
369             Simply calls L<input_value()|Rose::HTML::Form::Field/input_value>, passing all arguments.
370              
371             =item B<value_label [VALUE [, LABEL]]>
372              
373             If no arguments are passed, it returns the label of the first selected checkbox (according to the order that they are returned by L<internal_value()|Rose::HTML::Form::Field/internal_value>), or the value itself if it has no label. If no checkbox is selected, undef is returned.
374              
375             With arguments, it will 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.
376              
377             =item B<value_labels>
378              
379             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.
380              
381             =item B<xhtml>
382              
383             Returns the XHTML for checkbox group, which consists of the L<xhtml()|/xhtml> for each checkbox object joined by L<xhtml_linebreak()|/xhtml_linebreak> if L<linebreak()|/linebreak> is true, or single spaces if it is false.
384              
385             =item B<xhtml_linebreak [XHTML]>
386              
387             Get or set the XHTML linebreak string. The default is "E<lt>br /E<gt>\n"
388              
389             =item B<xhtml_table>
390              
391             Equivalent to L<html_table()|/html_table> but using XHTML markup for each checkbox.
392              
393             =back
394              
395             =head1 AUTHOR
396              
397             John C. Siracusa (siracusa@gmail.com)
398              
399             =head1 LICENSE
400              
401             Copyright (c) 2010 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.