1HTML::FormHandler::FielUds:e:rSeCloencttr(i3b)uted PerlHDToMcLu:m:eFnotramtHiaonndler::Field::Select(3)
2
6 HTML::FormHandler::Field::Select - select fields
7
9 version 0.40068
10
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 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 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 options
27 The 'options' array can come from a number of different places:
28 From a field declaration
30 In a field declaration:
31 has_field 'opt_in' => ( type => 'Select', widget => 'RadioGroup',
33 options => [{ value => 0, label => 'No'}, { value => 1, label => 'Yes'} ] );
34 From a field class 'build_options' method
36 In a custom field class:
37 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 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 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 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 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 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 See also HTML::FormHandler::Model::DBIC, the 'lookup_options'
88 method.
89 The options field should contain one of the following data structures:
91 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 ArrayRef
97 A list of key/value pairs corresponding to HTML field values and
98 labels.
99 ArrayRef containing one ArrayRef
101 Each item inside the inner ArrayRef defines both the label and
102 value of an option.
103 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 Note that you should *not* set 'checked' or 'selected' attributes in
110 options. That is handled by setting a field default.
111 An options array with an extra 'note' key:
113 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 Setting the select element to disabled:
129 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 You can also divide the options up into option groups. See the section
145 on rendering.
146 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 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
162 options
163 The options available for this field as defined in the "DESCRIPTION"
164 above.
165 options_method
167 Coderef of method to return options
168 multiple
170 If true allows multiple input values
171 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 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 has_field 'fruit' => ( type => 'Select',
182 empty_select => '---Choose a Fruit---' );
183 value_when_empty
185 Usually the empty value is an empty arrayref. This attribute allows
186 changing that. Used by SelectCSV field.
187 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 Refers to the method (or column) name to use in a related object class
193 for the label for select lists.
194 Defaults to "name".
196 localize_labels
198 For the renderers: whether or not to call the localize method on the
199 select labels. Default is off.
200 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 The default is "active".
207 If this column exists on the class then the list of options will
209 included only rows that are marked "active".
210 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 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 See select_widget below.
223 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 If not defined the label_column is used as the sort condition.
229 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 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 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 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
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 Option groups can be rendered by providing an options arrays with
257 'group' elements containing options:
258 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 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 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
288 Also see HTML::FormHandler::TraitFor::Model::DBIC.
289 The single select is for a DBIC 'belongs_to' relation. The multiple
291 select is for a 'many_to_many' relation.
292 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
303 FormHandler Contributors - see HTML::FormHandler
304
306 This software is copyright (c) 2017 by Gerda Shank.
307 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.
310perl v5.32.0 2020-07-28HTML::FormHandler::Field::Select(3)