1HTML::FormHandler::FielUds:e:rSeCloencttr(i3b)uted PerlHDToMcLu:m:eFnotramtHiaonndler::Field::Select(3)
2
3
4

NAME

6       HTML::FormHandler::Field::Select - select fields
7

VERSION

9       version 0.40068
10

DESCRIPTION

12       This is a field that includes a list of possible valid options.  This
13       can be used for select and multiple-select fields.  Widget type is
14       'select'.
15
16       Because select lists and checkbox_groups do not return an HTTP
17       parameter when the entire list is unselected, the Select field must
18       assume that the lack of a param means unselection. So to avoid setting
19       a Select field, it must be set to inactive, not merely not included in
20       the HTML for a form.
21
22       This field type can also be used for fields that use the 'radio_group'
23       widget, and the 'checkbox_group' widget (for selects with multiple flag
24       turned on, or that use the Multiple field).
25
26   options
27       The 'options' array can come from a number of different places:
28
29       From a field declaration
30           In a field declaration:
31
32              has_field 'opt_in' => ( type => 'Select', widget => 'RadioGroup',
33                 options => [{ value => 0, label => 'No'}, { value => 1, label => 'Yes'} ] );
34
35       From a field class 'build_options' method
36           In a custom field class:
37
38              package MyApp::Field::WeekDay;
39              use Moose;
40              extends 'HTML::FormHandler::Field::Select';
41              ....
42              sub build_options {
43                  my $i = 0;
44                  my @days = ('Sunday', 'Monday', 'Tuesday', 'Wednesday',
45                      'Thursday', 'Friday', 'Saturday' );
46                  return [
47                      map {
48                          {   value => $i++, label => $_ }
49                      } @days
50                  ];
51              }
52
53       From a coderef supplied to the field definition
54              has_field 'flim' => ( type => 'Select', options_method => \&flim_options );
55              sub flim_options {  <return options array> }
56
57       From a form 'options_<field_name>' method or attribute
58              has_field 'fruit' => ( type => 'Select' );
59              sub options_fruit {
60                  return (
61                      1   => 'apples',
62                      2   => 'oranges',
63                      3   => 'kiwi',
64                  );
65              }
66              -- or --
67              has 'options_fruit' => ( is => 'rw', traits => ['Array'],
68                  default => sub { [1 => 'apples', 2 => 'oranges',
69                      3 => 'kiwi'] } );
70
71           Notice that, as a convenience, you can return a simple array (or
72           arrayref) for the options array in the 'options_field_name' method.
73           The hashrefs with 'value' and 'label' keys will be constructed for
74           you by FormHandler.
75
76       From the database
77           The final source of the options array is a database when the name
78           of the accessor is a relation to the table holding the information
79           used to construct the select list.  The primary key is used as the
80           value. The other columns used are:
81
82               label_column  --  Used for the labels in the options (default 'name')
83               active_column --  The name of the column to be used in the query (default 'active')
84                                 that allows the rows retrieved to be restricted
85               sort_column   --  The name or arrayref of names of the column(s) used to sort the options
86
87           See also HTML::FormHandler::Model::DBIC, the 'lookup_options'
88           method.
89
90       The options field should contain one of the following data structures:
91
92       ArrayRef of HashRefs
93           Each hash reference defines an option, with the label and value
94           attributes corresponding to those of the HTML field.
95
96       ArrayRef
97           A list of key/value pairs corresponding to HTML field values and
98           labels.
99
100       ArrayRef containing one ArrayRef
101           Each item inside the inner ArrayRef defines both the label and
102           value of an option.
103
104   Customizing options
105       Additional attributes can be added in the options array hashref, by
106       using the 'attributes' key. If you have custom rendering code, you can
107       add any additional key that you want, of course.
108
109       Note that you should *not* set 'checked' or 'selected' attributes in
110       options.  That is handled by setting a field default.
111
112       An options array with an extra 'note' key:
113
114          sub options_license
115          {
116             my $self = shift;
117             return unless $self->schema;
118             my $licenses = $self->schema->resultset('License')->search({active => 1},
119                  {order_by => 'sequence'});
120             my @selections;
121             while ( my $license = $licenses->next ) {
122                push @selections, { value => $license->id, label => $license->label,
123                     note => $license->note };
124             }
125             return @selections;
126          }
127
128       Setting the select element to disabled:
129
130          sub options_license
131          {
132             my $self = shift;
133             return unless $self->schema;
134             my $licenses = $self->schema->resultset('License')->search(undef,
135                  {order_by => 'sequence'});
136             my @selections;
137             while ( my $license = $licenses->next ) {
138                push @selections, { value => $license->id, label => $license->label,
139                     attributes => { disabled => ($license->active == 0) ? 1 : 0 } };
140             }
141             return @selections;
142          }
143
144       You can also divide the options up into option groups. See the section
145       on rendering.
146
147   Reloading options
148       If the options come from the options_<fieldname> method or the
149       database, they will be reloaded every time the form is reloaded because
150       the available options may have changed. To prevent this from happening
151       when the available options are known to be static, set the
152       'do_not_reload' flag, and the options will not be reloaded after the
153       first time
154
155   Sorting options
156       The sorting of the options may be changed using a 'sort_options' method
157       in a custom field class. The 'Multiple' field uses this method to put
158       the already selected options at the top of the list. Note that this
159       won't work with option groups.
160

Attributes and Methods

162   options
163       The options available for this field as defined in the "DESCRIPTION"
164       above.
165
166   options_method
167       Coderef of method to return options
168
169   multiple
170       If true allows multiple input values
171
172   size
173       This can be used to store how many items should be offered in the UI at
174       a given time.  Defaults to 0.
175
176   empty_select
177       Set to the string value of the select label if you want the renderer to
178       create an empty select value. This only affects rendering - it does not
179       add an entry to the list of options.
180
181          has_field 'fruit' => ( type => 'Select',
182               empty_select => '---Choose a Fruit---' );
183
184   value_when_empty
185       Usually the empty value is an empty arrayref. This attribute allows
186       changing that. Used by SelectCSV field.
187
188   label_column
189       Sets or returns the name of the method to call on the foreign class to
190       fetch the text to use for the select list.
191
192       Refers to the method (or column) name to use in a related object class
193       for the label for select lists.
194
195       Defaults to "name".
196
197   localize_labels
198       For the renderers: whether or not to call the localize method on the
199       select labels. Default is off.
200
201   active_column
202       Sets or returns the name of a boolean column that is used as a flag to
203       indicate that a row is active or not.  Rows that are not active are
204       ignored.
205
206       The default is "active".
207
208       If this column exists on the class then the list of options will
209       included only rows that are marked "active".
210
211       The exception is any columns that are marked inactive, but are also
212       part of the input data will be included with brackets around the label.
213       This allows updating records that might have data that is now
214       considered inactive.
215
216   auto_widget_size
217       This is a way to provide a hint as to when to automatically select the
218       widget to display for fields with a small number of options.  For
219       example, this can be used to decided to display a radio select for
220       select lists smaller than the size specified.
221
222       See select_widget below.
223
224   sort_column
225       Sets or returns the column or arrayref of columns used in the foreign
226       class for sorting the options labels.  Default is undefined.
227
228       If not defined the label_column is used as the sort condition.
229
230   select_widget
231       If the widget is 'select' for the field then will look if the field
232       also has a auto_widget_size.  If the options list is less than or equal
233       to the auto_widget_size then will return "radio_group" if multiple is
234       false, otherwise will return "checkbox_group".
235
236   as_label
237       Returns the option label for the option value that matches the field's
238       current value.  Can be helpful for displaying information about the
239       field in a more friendly format.
240
241   no_option_validation
242       Set this flag to true if you don't want to validate the options that
243       are submitted.  This would generally only happen if the options are
244       generated via javascript.
245
246   error messages
247       Customize 'select_invalid_value' and 'select_not_multiple'. Though
248       neither of these messages should really be seen by users in a properly
249       constructed select.
250

Rendering

252       The 'select' field can be rendered by the 'Select', 'RadioGroup', and
253       'CheckboxGroup' widgets. 'RadioGroup' is for a single select, and
254       'CheckboxGroup' is for a multiple select.
255
256       Option groups can be rendered by providing an options arrays with
257       'group' elements containing options:
258
259           sub options_testop { (
260               {
261                   group => 'First Group',
262                   options => [
263                       { value => 1, label => 'One' },
264                       { value => 2, label => 'Two' },
265                       { value => 3, label => 'Three' },
266                   ],
267               },
268               {
269                   group => 'Second Group',
270                   options => [
271                       { value => 4, label => 'Four' },
272                       { value => 5, label => 'Five' },
273                       { value => 6, label => 'Six' },
274                   ],
275               },
276           ) }
277
278       The select rendering widgets all have a 'render_option' method, which
279       may be useful for situations when you want to split up the rendering of
280       a radio group or checkbox group.
281
282   Rendering with Template Toolkit
283       Calling 'options' from Template Toolkit can causes issues with
284       wantarray when there is only a single option. As a solution you should
285       use 'options_ref'.
286

Database relations

288       Also see HTML::FormHandler::TraitFor::Model::DBIC.
289
290       The single select is for a DBIC 'belongs_to' relation. The multiple
291       select is for a 'many_to_many' relation.
292
293       There is very limited ability to do multiple select with 'has_many'
294       relations.  It will only work in very specific circumstances, and
295       requires setting the 'has_many' attribute to the name of the primary
296       key of the related table.  This is a somewhat peculiar data structure
297       for a relational database, and may not be what you really want. A
298       'has_many' is usually represented with a Repeatable field, and may
299       require custom code if the form structure doesn't match the database
300       structure. See HTML::FormHandler::Manual::Cookbook.
301

AUTHOR

303       FormHandler Contributors - see HTML::FormHandler
304
306       This software is copyright (c) 2017 by Gerda Shank.
307
308       This is free software; you can redistribute it and/or modify it under
309       the same terms as the Perl 5 programming language system itself.
310
311
312
313perl v5.38.0                      2023-07-20HTML::FormHandler::Field::Select(3)
Impressum