1HTML::FormHandler::ManuUasle:r:DCeofnaturlitbsu(t3e)d PeHrTlMLD:o:cFuomremnHtaantdiloenr::Manual::Defaults(3)
2
3
4

NAME

6       HTML::FormHandler::Manual::Defaults - form defaults documentation
7

VERSION

9       version 0.40068
10

SYNOPSIS

12       Manual Index
13
14       How to set defaults for your fields.
15

Defaults

17       Defaults for form fields come from a number of different places. The
18       simplest way to set a field's default is on the field definition:
19
20          has_field 'foo' => ( type => 'Text', default => 'my_foo' );
21          has_field 'select_many' => ( type => 'Multiple', default => [1, 2, 3] );
22
23       You can also set the default for a field with a method in the form with
24       the name 'default_<field_name>', where any periods in the field name
25       are replaced with underscores.
26
27          has_field 'foo';
28          sub default_foo { 'my_default' }
29
30       Like other field attributes, the 'default' attribute can be modified on
31       new with the 'field_list' attribute, or on 'process' with the
32       'update_field_list' parameter (or the shorthand form 'defaults').
33
34          my $form => MyApp::Form->new( field_list => { '+foo' => { default => 'my_foo' } } );
35          $form->process( update_field_list => { foo => { default => 'my_foo' } } );
36          $form->process( defaults => { foo => 'my_foo' }, params => $params );
37
38       For forms where you pass in an 'item' (usually a database row object),
39       the values in that object will be used preferentially; if an accessor
40       exists in the 'item' object, then the defaults won't be used. (If an
41       accessor doesn't exist, the defaults *will* be used.)
42
43          $form->process( item => $row, params => {} );
44
45       For the above call the 'default' on the field will not be used, which
46       is usually what you want.
47
48       When creating a new database record with your form, if you don't pass
49       in an empty row, then the field defaults will be used, or you can
50       provide defaults in an 'init_object'.
51
52          note: the form class has 'item_class' set already.
53          $form->process( schema => $schema, init_object => $obj ... );
54
55       If you provide an empty row object for 'create' type actions, however,
56       you might want some defaults filled in. This can be done by filling the
57       values into the row object or by turning on the form flag
58       'use_defaults_over_obj'.
59
60          $form->process( item => $empty_row, use_defaults_over_obj => 1 );
61
62       If you always want new DBIC results to be ignored, you could set the
63       flag in a base form method:
64
65           sub set_active {
66               my $self = shift;
67               $self->next::method;
68               if ( $self->item and ! $self->item->in_storage ) {
69                   $self->use_defaults_over_obj(1);
70               }
71           }
72
73       You could also pass in another object or hashref in the 'init_object'
74       attribute, and set the 'use_init_obj_over_item' flag:
75
76          $form->process( item => $empty_row, init_object => $example,
77                          use_init_obj_over_item => 1 );
78
79       Note that the 'use_init_obj_over_item' and 'use_defaults_over_obj'
80       flags are automatically cleared (if you're using persistent forms).
81
82       For forms where some defaults come from a database row, and some
83       defaults come from some other dynamic source (so that putting them into
84       the field definitions doesn't make sense), you can use the
85       'use_init_obj_when_no_accessor_in_item' flag to provide two different
86       sets of defaults, one set in the 'item' (usually a db row) and one set
87       in the init_obj. If the 'item' is undefined, the values in the
88       init_object are used.
89
90           in form: has '+use_init_obj_when_no_accessor_in_item' => ( default => 1 );
91           $form->process( item => $item, init_object => { foo => '...' }, .. );
92
93       There is a convenience method for setting 'defaults' on a number of
94       fields at once, the form's 'defaults' attribute, which uses the same
95       mechanism as 'update_field_list' but only sets defaults. Note that this
96       hashref is structured like the update_field_list with regard to field
97       names, while the 'init_object' uses "structured" data:
98
99          my $defaults = {
100              model => 'standard',
101              'opts.color' => 'Red',
102              'opts.size'  => 'Big',
103          };
104          my $init_object => {
105              model => 'standard',
106              opts  => { color => 'Red', size => 'Big' }
107          };
108
109          $form->process( defaults => $defaults, ... );
110          $form->process( init_object => $init_object ... );
111
112       In addition, the 'defaults' actually changes the 'default' stored in
113       the field definitions, while the init_object does not.
114
115       There is also an alternative attribute in the fields,
116       'default_over_obj', but the new 'use_defaults_over_obj' and
117       'use_init_obj_over_item' flags, make it less necessary. Note that the
118       'default_over_obj' attribute only provides a default if an
119       item/init_object and accessor exists.
120
121   Defaults when processing params
122       Normally when a form is posted, the params will contain all the values
123       that are necessary to fill in the form. However, when a form is used in
124       an API-like fashion, such as complex search forms, sometimes it is
125       convenient to only provide particular params and let the others use
126       defaults. However when the results are built from input, fields with no
127       input are skipped unless the field has a value for
128       'input_without_param'.  There is an additional form-level flag,
129       'use_fields_for_input_without_param' which will cause fields with no
130       param entry to be built from the fields.  This means that 'defaults' on
131       the field will be used to provide a value and an input for the field.
132
133   Query parameters for defaults
134       You can use either the 'defaults' hashref or the 'init_object' to
135       provide query parameter 'defaults'. They should not be provided in the
136       'params' hash, because then FormHandler will assume that the form has
137       been posted and attempt to validate, which you don't want to do until
138       the form has been submitted. Or you can use the 'posted' flag, to
139       indicate whether or not to perform validation:
140
141           $form->process( posted => ( $c->req->method eq 'POST' ), params => $c->req->params );
142
143       Note that in Catalyst, there are 'query_parameters' and
144       'body_parameters'. The 'parameters' contains both 'query_parameters'
145       and 'body_parameters'.
146

AUTHOR

148       FormHandler Contributors - see HTML::FormHandler
149

151       This software is copyright (c) 2017 by Gerda Shank.
152
153       This is free software; you can redistribute it and/or modify it under
154       the same terms as the Perl 5 programming language system itself.
155
156
157
158perl v5.30.1                      2020-01H-T3M0L::FormHandler::Manual::Defaults(3)
Impressum