Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rose::HTML::Form::FielUserhContributedoPe::HTML::Form::Field::CheckboxGroup(3)

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

HIERARCHY
       A checkbox group	is an abstraction with no corresponding	parent HTML
       element;	the individual checkbox	objects	in the group exist as
       siblings.  As such, the list of child objects will always be empty and
       cannot be modified.  To get the list of siblings, use the checkboxes
       method.

       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
       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 take the
	   following forms.

	   A reference to a hash of value/label	pairs:

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

	   An ordered list of value/label pairs:

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

	   (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.)

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

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

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

	       $field->add_checkboxes
	       (
		 Rose::HTML::Form::Field::Checkbox->new(...),
		 Rose::HTML::Form::Field::Checkbox->new(...),
		 ...
	       );

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

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

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

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

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

		 ...
	       );

	       $field->add_checkboxes(@args);  # list
	       $field->add_checkboxes(\@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 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, an ordered list
	   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.	 Hidden
	   checkboxes will be included in this list.  These are	the actual
	   objects used	in the field. Modifying	them will modify the field
	   itself.

       choices [CHECKBOXES]
	   This	is an alias for	the checkboxes method.

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

       checkboxes_html_attr NAME [, VALUE]
	   If VALUE is passed, set the HTML attribute named NAME on all
	   checkboxes.	Otherwise, return the value of the  HTML attribute
	   named NAME on the first checkbox encountered	in the list of all
	   checkboxes.

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

       delete_checkboxes LIST
	   Repeatedly calls delete_checkbox, passing each value	in LIST.

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

       delete_checkboxes_html_attr NAME
	   Delete the HTML attribute named NAME	from each checkbox.

       delete_items_html_attr NAME
	   This	is an alias for	the delete_checkboxes_html_attr	method.

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

       hide_all_checkboxes
	   Set hidden to true for all checkboxes.

       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:

	   class
	       The value of the	"table"	tag's "class" HTML attribute.
	       Defaults	to "checkbox-group".  Any value	passed for this
	       attribute joined	to "checkbox-group" with a single space.

	   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.

	   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 a reference to an
	       empty hash, "{}".

	   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.

       items_html_attr NAME [, VALUE]
	   This	is an alias for	the checkboxes_html_attr method.

       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.

       show_all_checkboxes
	   Set hidden to false for all checkboxes.

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

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

       value_label [VALUE [, LABEL]]
	   If no arguments are passed, it 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.

	   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.

       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() but using	XHTML markup for each
	   checkbox.

AUTHOR
       John C. Siracusa	(siracusa@gmail.com)

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

perl v5.32.0			  201Rose::HTML::Form::Field::CheckboxGroup(3)

NAME | SYNOPSIS | DESCRIPTION | HIERARCHY | HTML ATTRIBUTES | CONSTRUCTOR | OBJECT METHODS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rose::HTML::Form::Field::CheckboxGroup&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help