.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "HTML::FormHandler::Manual::Defaults 3pm"
.TH HTML::FormHandler::Manual::Defaults 3pm "2017-11-11" "perl v5.26.1" "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::Manual::Defaults \- form defaults documentation
.SH "VERSION"
.IX Header "VERSION"
version 0.40068
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Manual Index
.PP
How to set defaults for your fields.
.SH "Defaults"
.IX Header "Defaults"
Defaults for form fields come from a number of different places. The simplest
way to set a field's default is on the field definition:
.PP
.Vb 2
\&   has_field \*(Aqfoo\*(Aq => ( type => \*(AqText\*(Aq, default => \*(Aqmy_foo\*(Aq );
\&   has_field \*(Aqselect_many\*(Aq => ( type => \*(AqMultiple\*(Aq, default => [1, 2, 3] );
.Ve
.PP
You can also set the default for a field with a method in the form with the name
\&'default_<field_name>', where any periods in the field name are replaced
with underscores.
.PP
.Vb 2
\&   has_field \*(Aqfoo\*(Aq;
\&   sub default_foo { \*(Aqmy_default\*(Aq }
.Ve
.PP
Like other field attributes, the 'default' attribute can be modified on
new with the 'field_list' attribute, or on 'process' with the 'update_field_list'
parameter (or the shorthand form 'defaults').
.PP
.Vb 3
\&   my $form => MyApp::Form\->new( field_list => { \*(Aq+foo\*(Aq => { default => \*(Aqmy_foo\*(Aq } } );
\&   $form\->process( update_field_list => { foo => { default => \*(Aqmy_foo\*(Aq } } );
\&   $form\->process( defaults => { foo => \*(Aqmy_foo\*(Aq }, params => $params );
.Ve
.PP
For forms where you pass in an 'item' (usually a database row object), the
values in that object will be used preferentially; if an accessor exists
in the 'item' object, then the defaults won't be used. (If an accessor
doesn't exist, the defaults *will* be used.)
.PP
.Vb 1
\&   $form\->process( item => $row, params => {} );
.Ve
.PP
For the above call the 'default' on the field will not be used, which is
usually what you want.
.PP
When creating a new database record with your form, if you don't pass in an
empty row, then the field defaults will be used, or you can provide defaults
in an 'init_object'.
.PP
.Vb 2
\&   note: the form class has \*(Aqitem_class\*(Aq set already.
\&   $form\->process( schema => $schema, init_object => $obj ... );
.Ve
.PP
If you provide an empty row object for 'create' type
actions, however, you might want some defaults filled in. This can
be done by filling the values into the row object or by turning on the form
flag 'use_defaults_over_obj'.
.PP
.Vb 1
\&   $form\->process( item => $empty_row, use_defaults_over_obj => 1 );
.Ve
.PP
If you always want new \s-1DBIC\s0 results to be ignored, you could set the flag in
a base form method:
.PP
.Vb 7
\&    sub set_active {
\&        my $self = shift;
\&        $self\->next::method;
\&        if ( $self\->item and ! $self\->item\->in_storage ) {
\&            $self\->use_defaults_over_obj(1);
\&        }
\&    }
.Ve
.PP
You could also pass in another object or hashref in the 'init_object' attribute,
and set the 'use_init_obj_over_item' flag:
.PP
.Vb 2
\&   $form\->process( item => $empty_row, init_object => $example,
\&                   use_init_obj_over_item => 1 );
.Ve
.PP
Note that the 'use_init_obj_over_item' and 'use_defaults_over_obj' flags
are automatically cleared (if you're using persistent forms).
.PP
For forms where some defaults come from a database row, and some defaults
come from some other dynamic source (so that putting them into the field
definitions doesn't make sense), you can use the
\&'use_init_obj_when_no_accessor_in_item' flag to provide two different
sets of defaults, one set in the 'item' (usually a db row) and one set in
the init_obj. If the 'item' is undefined, the values in the init_object
are used.
.PP
.Vb 2
\&    in form: has \*(Aq+use_init_obj_when_no_accessor_in_item\*(Aq => ( default => 1 );
\&    $form\->process( item => $item, init_object => { foo => \*(Aq...\*(Aq }, .. );
.Ve
.PP
There is a convenience method for setting 'defaults' on a number of fields at
once, the form's 'defaults' attribute, which uses the same mechanism as
\&'update_field_list' but only sets defaults. Note that this hashref is
structured like the update_field_list with regard to field names,
while the 'init_object' uses \*(L"structured\*(R" data:
.PP
.Vb 9
\&   my $defaults = {
\&       model => \*(Aqstandard\*(Aq,
\&       \*(Aqopts.color\*(Aq => \*(AqRed\*(Aq,
\&       \*(Aqopts.size\*(Aq  => \*(AqBig\*(Aq,
\&   };
\&   my $init_object => {
\&       model => \*(Aqstandard\*(Aq,
\&       opts  => { color => \*(AqRed\*(Aq, size => \*(AqBig\*(Aq }
\&   };
\&
\&   $form\->process( defaults => $defaults, ... );
\&   $form\->process( init_object => $init_object ... );
.Ve
.PP
In addition, the 'defaults' actually changes the 'default' stored in
the field definitions, while the init_object does not.
.PP
There is also an alternative attribute in the fields, 'default_over_obj', but
the new 'use_defaults_over_obj' and 'use_init_obj_over_item' flags, make it less
necessary. Note that the 'default_over_obj' attribute only provides a default if
an item/init_object and accessor exists.
.SS "Defaults when processing params"
.IX Subsection "Defaults when processing params"
Normally when a form is posted, the params will contain all the values
that are necessary to fill in the form. However, when a form is used in
an API-like fashion, such as complex search forms, sometimes it is
convenient to only provide particular params and let the others use
defaults. However when the results are built from input, fields with
no input are skipped unless the field has a value for 'input_without_param'.
There is an additional form-level flag, 'use_fields_for_input_without_param'
which will cause fields with no param entry to be built from the fields.
This means that 'defaults' on the field will be used to provide a value
and an input for the field.
.SS "Query parameters for defaults"
.IX Subsection "Query parameters for defaults"
You can use either the 'defaults' hashref or the 'init_object' to provide query
parameter 'defaults'. They should not be provided in the 'params' hash, because
then FormHandler will assume that the form has been posted and attempt to validate,
which you don't want to do until the form has been submitted. Or you can use
the 'posted' flag, to indicate whether or not to perform validation:
.PP
.Vb 1
\&    $form\->process( posted => ( $c\->req\->method eq \*(AqPOST\*(Aq ), params => $c\->req\->params );
.Ve
.PP
Note that in Catalyst, there are 'query_parameters' and 'body_parameters'. The
\&'parameters' contains both 'query_parameters' and 'body_parameters'.
.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.