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

FreeBSD Manual Pages

  
 
  

home | help
HTML::FormHandler::FieUserSContributed PerlHTML::FormHandler::Field::Select(3)

NAME
       HTML::FormHandler::Field::Select	- select fields

VERSION
       version 0.40067

DESCRIPTION
       This is a field that includes a list of possible	valid options.	This
       can be used for select and multiple-select fields.  Widget type is
       'select'.

       Because select lists and	checkbox_groups	do not return an HTTP
       parameter when the entire list is unselected, the Select	field must
       assume that the lack of a param means unselection. So to	avoid setting
       a Select	field, it must be set to inactive, not merely not included in
       the HTML	for a form.

       This field type can also	be used	for fields that	use the	'radio_group'
       widget, and the 'checkbox_group'	widget (for selects with multiple flag
       turned on, or that use the Multiple field).

   options
       The 'options' array can come from a number of different places:

       From a field declaration
	   In a	field declaration:

	      has_field	'opt_in' => ( type => 'Select',	widget => 'RadioGroup',
		 options => [{ value =>	0, label => 'No'}, { value => 1, label => 'Yes'} ] );

       From a field class 'build_options' method
	   In a	custom field class:

	      package MyApp::Field::WeekDay;
	      use Moose;
	      extends 'HTML::FormHandler::Field::Select';
	      ....
	      sub build_options	{
		  my $i	= 0;
		  my @days = ('Sunday',	'Monday', 'Tuesday', 'Wednesday',
		      'Thursday', 'Friday', 'Saturday' );
		  return [
		      map {
			  {   value => $i++, label => $_ }
		      }	@days
		  ];
	      }

       From a coderef supplied to the field definition
	      has_field	'flim' => ( type => 'Select', options_method =>	\&flim_options );
	      sub flim_options {  <return options array> }

       From a form 'options_<field_name>' method or attribute
	      has_field	'fruit'	=> ( type => 'Select' );
	      sub options_fruit	{
		  return (
		      1	  => 'apples',
		      2	  => 'oranges',
		      3	  => 'kiwi',
		  );
	      }
	      -- or --
	      has 'options_fruit' => ( is => 'rw', traits => ['Array'],
		  default => sub { [1 => 'apples', 2 =>	'oranges',
		      3	=> 'kiwi'] } );

	   Notice that,	as a convenience, you can return a simple array	(or
	   arrayref) for the options array in the 'options_field_name' method.
	   The hashrefs	with 'value' and 'label' keys will be constructed for
	   you by FormHandler.

       From the	database
	   The final source of the options array is a database when the	name
	   of the accessor is a	relation to the	table holding the information
	   used	to construct the select	list.  The primary key is used as the
	   value. The other columns used are:

	       label_column  --	 Used for the labels in	the options (default 'name')
	       active_column --	 The name of the column	to be used in the query	(default 'active')
				 that allows the rows retrieved	to be restricted
	       sort_column   --	 The name or arrayref of names of the column(s)	used to	sort the options

	   See also HTML::FormHandler::Model::DBIC, the	'lookup_options'
	   method.

       The options field should	contain	one of the following data structures:

       ArrayRef	of HashRefs
	   Each	hash reference defines an option, with the label and value
	   attributes corresponding to those of	the HTML field.

       ArrayRef
	   A list of key/value pairs corresponding to HTML field values	and
	   labels.

       ArrayRef	containing one ArrayRef
	   Each	item inside the	inner ArrayRef defines both the	label and
	   value of an option.

   Customizing options
       Additional attributes can be added in the options array hashref,	by
       using the 'attributes' key. If you have custom rendering	code, you can
       add any additional key that you want, of	course.

       Note that you should *not* set 'checked'	or 'selected' attributes in
       options.	 That is handled by setting a field default.

       An options array	with an	extra 'note' key:

	  sub options_license
	  {
	     my	$self =	shift;
	     return unless $self->schema;
	     my	$licenses = $self->schema->resultset('License')->search({active	=> 1},
		  {order_by => 'sequence'});
	     my	@selections;
	     while ( my	$license = $licenses->next ) {
		push @selections, { value => $license->id, label => $license->label,
		     note => $license->note };
	     }
	     return @selections;
	  }

       Setting the select element to disabled:

	  sub options_license
	  {
	     my	$self =	shift;
	     return unless $self->schema;
	     my	$licenses = $self->schema->resultset('License')->search(undef,
		  {order_by => 'sequence'});
	     my	@selections;
	     while ( my	$license = $licenses->next ) {
		push @selections, { value => $license->id, label => $license->label,
		     attributes	=> { disabled => ($license->active == 0) ? 1 : 0 } };
	     }
	     return @selections;
	  }

       You can also divide the options up into option groups. See the section
       on rendering.

   Reloading options
       If the options come from	the options_<fieldname>	method or the
       database, they will be reloaded every time the form is reloaded because
       the available options may have changed. To prevent this from happening
       when the	available options are known to be static, set the
       'do_not_reload' flag, and the options will not be reloaded after	the
       first time

   Sorting options
       The sorting of the options may be changed using a 'sort_options'	method
       in a custom field class.	The 'Multiple' field uses this method to put
       the already selected options at the top of the list. Note that this
       won't work with option groups.

Attributes and Methods
   options
       The options available for this field as defined in the "DESCRIPTION"
       above.

   options_method
       Coderef of method to return options

   multiple
       If true allows multiple input values

   size
       This can	be used	to store how many items	should be offered in the UI at
       a given time.  Defaults to 0.

   empty_select
       Set to the string value of the select label if you want the renderer to
       create an empty select value. This only affects rendering - it does not
       add an entry to the list	of options.

	  has_field 'fruit' => ( type => 'Select',
	       empty_select => '---Choose a Fruit---' );

   value_when_empty
       Usually the empty value is an empty arrayref. This attribute allows
       changing	that. Used by SelectCSV	field.

   label_column
       Sets or returns the name	of the method to call on the foreign class to
       fetch the text to use for the select list.

       Refers to the method (or	column)	name to	use in a related object	class
       for the label for select	lists.

       Defaults	to "name".

   localize_labels
       For the renderers: whether or not to call the localize method on	the
       select labels. Default is off.

   active_column
       Sets or returns the name	of a boolean column that is used as a flag to
       indicate	that a row is active or	not.  Rows that	are not	active are
       ignored.

       The default is "active".

       If this column exists on	the class then the list	of options will
       included	only rows that are marked "active".

       The exception is	any columns that are marked inactive, but are also
       part of the input data will be included with brackets around the	label.
       This allows updating records that might have data that is now
       considered inactive.

   auto_widget_size
       This is a way to	provide	a hint as to when to automatically select the
       widget to display for fields with a small number	of options.  For
       example,	this can be used to decided to display a radio select for
       select lists smaller than the size specified.

       See select_widget below.

   sort_column
       Sets or returns the column or arrayref of columns used in the foreign
       class for sorting the options labels.  Default is undefined.

       If not defined the label_column is used as the sort condition.

   select_widget
       If the widget is	'select' for the field then will look if the field
       also has	a auto_widget_size.  If	the options list is less than or equal
       to the auto_widget_size then will return	"radio_group" if multiple is
       false, otherwise	will return "checkbox_group".

   as_label
       Returns the option label	for the	option value that matches the field's
       current value.  Can be helpful for displaying information about the
       field in	a more friendly	format.

   no_option_validation
       Set this	flag to	true if	you don't want to validate the options that
       are submitted.  This would generally only happen	if the options are
       generated via javascript.

   error messages
       Customize 'select_invalid_value'	and 'select_not_multiple'. Though
       neither of these	messages should	really be seen by users	in a properly
       constructed select.

Rendering
       The 'select' field can be rendered by the 'Select', 'RadioGroup', and
       'CheckboxGroup' widgets.	'RadioGroup' is	for a single select, and
       'CheckboxGroup' is for a	multiple select.

       Option groups can be rendered by	providing an options arrays with
       'group' elements	containing options:

	   sub options_testop {	(
	       {
		   group => 'First Group',
		   options => [
		       { value => 1, label => 'One' },
		       { value => 2, label => 'Two' },
		       { value => 3, label => 'Three' },
		   ],
	       },
	       {
		   group => 'Second Group',
		   options => [
		       { value => 4, label => 'Four' },
		       { value => 5, label => 'Five' },
		       { value => 6, label => 'Six' },
		   ],
	       },
	   ) }

       The select rendering widgets all	have a 'render_option' method, which
       may be useful for situations when you want to split up the rendering of
       a radio group or	checkbox group.

   Rendering with Template Toolkit
       Calling 'options' from Template Toolkit can causes issues with
       wantarray when there is only a single option. As	a solution you should
       use 'options_ref'.

Database relations
       Also see	HTML::FormHandler::TraitFor::Model::DBIC.

       The single select is for	a DBIC 'belongs_to' relation. The multiple
       select is for a 'many_to_many' relation.

       There is	very limited ability to	do multiple select with	'has_many'
       relations.  It will only	work in	very specific circumstances, and
       requires	setting	the 'has_many' attribute to the	name of	the primary
       key of the related table.  This is a somewhat peculiar data structure
       for a relational	database, and may not be what you really want. A
       'has_many' is usually represented with a	Repeatable field, and may
       require custom code if the form structure doesn't match the database
       structure. See HTML::FormHandler::Manual::Cookbook.

AUTHOR
       FormHandler Contributors	- see HTML::FormHandler

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2016 by Gerda Shank.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2016-10-1HTML::FormHandler::Field::Select(3)

NAME | VERSION | DESCRIPTION | Attributes and Methods | Rendering | Database relations | AUTHOR | COPYRIGHT AND LICENSE

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

home | help