.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTML::FormHandler::Field::Select 3pm" .TH HTML::FormHandler::Field::Select 3pm "2022-03-25" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTML::FormHandler::Field::Select \- select fields .SH "VERSION" .IX Header "VERSION" version 0.40068 .SH "DESCRIPTION" .IX Header "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'. .PP Because select lists and checkbox_groups do not return an \s-1HTTP\s0 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 \s-1HTML\s0 for a form. .PP 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). .SS "options" .IX Subsection "options" The 'options' array can come from a number of different places: .IP "From a field declaration" 4 .IX Item "From a field declaration" In a field declaration: .Sp .Vb 2 \& has_field \*(Aqopt_in\*(Aq => ( type => \*(AqSelect\*(Aq, widget => \*(AqRadioGroup\*(Aq, \& options => [{ value => 0, label => \*(AqNo\*(Aq}, { value => 1, label => \*(AqYes\*(Aq} ] ); .Ve .IP "From a field class 'build_options' method" 4 .IX Item "From a field class 'build_options' method" In a custom field class: .Sp .Vb 10 \& package MyApp::Field::WeekDay; \& use Moose; \& extends \*(AqHTML::FormHandler::Field::Select\*(Aq; \& .... \& sub build_options { \& my $i = 0; \& my @days = (\*(AqSunday\*(Aq, \*(AqMonday\*(Aq, \*(AqTuesday\*(Aq, \*(AqWednesday\*(Aq, \& \*(AqThursday\*(Aq, \*(AqFriday\*(Aq, \*(AqSaturday\*(Aq ); \& return [ \& map { \& { value => $i++, label => $_ } \& } @days \& ]; \& } .Ve .IP "From a coderef supplied to the field definition" 4 .IX Item "From a coderef supplied to the field definition" .Vb 2 \& has_field \*(Aqflim\*(Aq => ( type => \*(AqSelect\*(Aq, options_method => \e&flim_options ); \& sub flim_options { } .Ve .IP "From a form 'options_' method or attribute" 4 .IX Item "From a form 'options_' method or attribute" .Vb 12 \& has_field \*(Aqfruit\*(Aq => ( type => \*(AqSelect\*(Aq ); \& sub options_fruit { \& return ( \& 1 => \*(Aqapples\*(Aq, \& 2 => \*(Aqoranges\*(Aq, \& 3 => \*(Aqkiwi\*(Aq, \& ); \& } \& \-\- or \-\- \& has \*(Aqoptions_fruit\*(Aq => ( is => \*(Aqrw\*(Aq, traits => [\*(AqArray\*(Aq], \& default => sub { [1 => \*(Aqapples\*(Aq, 2 => \*(Aqoranges\*(Aq, \& 3 => \*(Aqkiwi\*(Aq] } ); .Ve .Sp 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. .IP "From the database" 4 .IX Item "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: .Sp .Vb 4 \& label_column \-\- Used for the labels in the options (default \*(Aqname\*(Aq) \& active_column \-\- The name of the column to be used in the query (default \*(Aqactive\*(Aq) \& 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 .Ve .Sp See also HTML::FormHandler::Model::DBIC, the 'lookup_options' method. .PP The options field should contain one of the following data structures: .IP "ArrayRef of HashRefs" 4 .IX Item "ArrayRef of HashRefs" Each hash reference defines an option, with the label and value attributes corresponding to those of the \s-1HTML\s0 field. .IP "ArrayRef" 4 .IX Item "ArrayRef" A list of key/value pairs corresponding to \s-1HTML\s0 field values and labels. .IP "ArrayRef containing one ArrayRef" 4 .IX Item "ArrayRef containing one ArrayRef" Each item inside the inner ArrayRef defines both the label and value of an option. .SS "Customizing options" .IX Subsection "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. .PP Note that you should *not* set 'checked' or 'selected' attributes in options. That is handled by setting a field default. .PP An options array with an extra 'note' key: .PP .Vb 10 \& sub options_license \& { \& my $self = shift; \& return unless $self\->schema; \& my $licenses = $self\->schema\->resultset(\*(AqLicense\*(Aq)\->search({active => 1}, \& {order_by => \*(Aqsequence\*(Aq}); \& my @selections; \& while ( my $license = $licenses\->next ) { \& push @selections, { value => $license\->id, label => $license\->label, \& note => $license\->note }; \& } \& return @selections; \& } .Ve .PP Setting the select element to disabled: .PP .Vb 10 \& sub options_license \& { \& my $self = shift; \& return unless $self\->schema; \& my $licenses = $self\->schema\->resultset(\*(AqLicense\*(Aq)\->search(undef, \& {order_by => \*(Aqsequence\*(Aq}); \& my @selections; \& while ( my $license = $licenses\->next ) { \& push @selections, { value => $license\->id, label => $license\->label, \& attributes => { disabled => ($license\->active == 0) ? 1 : 0 } }; \& } \& return @selections; \& } .Ve .PP You can also divide the options up into option groups. See the section on rendering. .SS "Reloading options" .IX Subsection "Reloading options" If the options come from the options_ 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 .SS "Sorting options" .IX Subsection "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. .SH "Attributes and Methods" .IX Header "Attributes and Methods" .SS "options" .IX Subsection "options" The options available for this field as defined in the \*(L"\s-1DESCRIPTION\*(R"\s0 above. .SS "options_method" .IX Subsection "options_method" Coderef of method to return options .SS "multiple" .IX Subsection "multiple" If true allows multiple input values .SS "size" .IX Subsection "size" This can be used to store how many items should be offered in the \s-1UI\s0 at a given time. Defaults to 0. .SS "empty_select" .IX Subsection "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. .PP .Vb 2 \& has_field \*(Aqfruit\*(Aq => ( type => \*(AqSelect\*(Aq, \& empty_select => \*(Aq\-\-\-Choose a Fruit\-\-\-\*(Aq ); .Ve .SS "value_when_empty" .IX Subsection "value_when_empty" Usually the empty value is an empty arrayref. This attribute allows changing that. Used by SelectCSV field. .SS "label_column" .IX Subsection "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. .PP Refers to the method (or column) name to use in a related object class for the label for select lists. .PP Defaults to \*(L"name\*(R". .SS "localize_labels" .IX Subsection "localize_labels" For the renderers: whether or not to call the localize method on the select labels. Default is off. .SS "active_column" .IX Subsection "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. .PP The default is \*(L"active\*(R". .PP If this column exists on the class then the list of options will included only rows that are marked \*(L"active\*(R". .PP 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. .SS "auto_widget_size" .IX Subsection "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. .PP See select_widget below. .SS "sort_column" .IX Subsection "sort_column" Sets or returns the column or arrayref of columns used in the foreign class for sorting the options labels. Default is undefined. .PP If not defined the label_column is used as the sort condition. .SS "select_widget" .IX Subsection "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 \f(CW\*(C`radio_group\*(C'\fR if multiple is false, otherwise will return \f(CW\*(C`checkbox_group\*(C'\fR. .SS "as_label" .IX Subsection "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. .SS "no_option_validation" .IX Subsection "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. .SS "error messages" .IX Subsection "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. .SH "Rendering" .IX Header "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. .PP Option groups can be rendered by providing an options arrays with 'group' elements containing options: .PP .Vb 10 \& sub options_testop { ( \& { \& group => \*(AqFirst Group\*(Aq, \& options => [ \& { value => 1, label => \*(AqOne\*(Aq }, \& { value => 2, label => \*(AqTwo\*(Aq }, \& { value => 3, label => \*(AqThree\*(Aq }, \& ], \& }, \& { \& group => \*(AqSecond Group\*(Aq, \& options => [ \& { value => 4, label => \*(AqFour\*(Aq }, \& { value => 5, label => \*(AqFive\*(Aq }, \& { value => 6, label => \*(AqSix\*(Aq }, \& ], \& }, \& ) } .Ve .PP 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. .SS "Rendering with Template Toolkit" .IX Subsection "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'. .SH "Database relations" .IX Header "Database relations" Also see HTML::FormHandler::TraitFor::Model::DBIC. .PP The single select is for a \s-1DBIC\s0 'belongs_to' relation. The multiple select is for a 'many_to_many' relation. .PP 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. .SH "AUTHOR" .IX Header "AUTHOR" FormHandler Contributors \- see HTML::FormHandler .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2017 by Gerda Shank. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.