HTML::FormHandler::FieUserSContributed PerlHTML::FormHandler::Field::Select(3)NAMEHTML::FormHandler::Field::Select - select fields
VERSION
version 0.35005
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).
The 'options' array can come from four different places. The options
attribute itself, either declaratively or using a 'build_options'
method in the field, from a method in the form ('options_<fieldname>')
or from the database.
In a field declaration:
has_field 'opt_in' => ( type => 'Select', widget => 'radio_group',
options => [{ value => 0, label => 'No'}, { value => 1, label => 'Yes'} ] );
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
];
}
In a form:
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. The arrayref of hashrefs format can be useful if you want
to add another key to the hashes that you can use in creating the HTML:
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;
}
To have an option being shown, but disabled (thus not selectable), use
the 'disabled' key with a true value inside this hashref. Let's extend
the example above, adding also inactive licenses, and disabling them.
Keep in mind that a disabled option can be made selectable later, by
removing the disabled attribute, e.g. using javascript.
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,
note => $license->note, disabled => ($license->active == 0) ? 1 : 0 };
}
return @selections;
}
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 of the column used to sort the options
See also HTML::FormHandler::Model::DBIC, the 'lookup_options' method.
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
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.
Attributes and Methods
options
This is an array of hashes for this field. Each has must have a label
and value keys.
set_options
Name of form method that sets 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---' );
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 used in the foreign class for sorting the
options labels. Default is undefined.
If this column exists in the foreign table then labels returned will be
sorted by this column.
If not defined or the column is not found as a method on the foreign
class then 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. This does a string compare.
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.
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) 2011 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.14.12011-10-0HTML::FormHandler::Field::Select(3)
