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

FreeBSD Manual Pages

  
 
  

home | help
Rose::HTML::Form::FielUsereContributed PeRose::HTML::Form::Field::SelectBox(3)

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
       Rose::HTML::Form::Field::SelectBox is an	object representation of a
       select box field	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
       All child-related methods are effectively aliases for the option
       manipulation methods described below.  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
       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 Rose::HTML::Form::Field::SelectBox 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
	   the keys of the hash	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 Rose::HTML::Form::Field::Option
	   or Rose::HTML::Form::Field::OptionGroup 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 Rose::HTML::Form::Field::Option or
	   Rose::HTML::Form::Field::OptionGroup	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_items_html_attr NAME
	   This	is an alias for	the delete_options_html_attr 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.

       delete_options_html_attr	NAME
	   Delete the HTML attribute named NAME	from each option.

       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.

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

       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 of	value/label pairs in scalar context.

       label_ids [LABELS]
	   Get or set the integer message ids for all values.  If LABELS is a
	   reference to	a hash or a list of value/message id pairs, then
	   LABELS replaces all existing	label ids.

	   Returns a hash of value/label pairs in list context,	or a reference
	   to a	hash of	value/label pairs 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
	   Rose::HTML::Form::Field::Option or
	   Rose::HTML::Form::Field::OptionGroup. 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 Rose::Object 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 Rose::HTML::Form::Field::Option
	   and/or Rose::HTML::Form::Field::OptionGroup 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 Rose::HTML::Form::Field::OptionGroup object whose
	   "label" HTML	attribute is LABEL, or undef if	no such	option group
	   exists.

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

       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)

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			  2015-03Rose::HTML::Form::Field::SelectBox(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::SelectBox&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help