NAME

HTML::FormHandler::Field::Select

DESCRIPTION

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

This field type can also be used for fields that use the 'radio_group' widget.

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:

   sub build_options {
       my $i = 0;
       my @days = ('Sunday', 'Monday', 'Tuesday', 'Wednesday',
           'Thursday', 'Friday', 'Saturday' );
       return [
           map {
               {   value => $i++, label => $_ }
           } @days
       ];
   }

In a form:

   sub options_fruit {
       return (
           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; 
   }

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"

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.

AUTHORS

Gerda Shank, gshank@cpan.org

Based on the original source code of Form::Processor::Field::Select by Bill Moseley

COPYRIGHT

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm HTML::FormHandler

perl -MCPAN -e shell
install HTML::FormHandler