.\" 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::Manual::Database 3pm"
.TH HTML::FormHandler::Manual::Database 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::Manual::Database \- FormHandler use recipes
.SH "VERSION"
.IX Header "VERSION"
version 0.40068
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Manual Index
.PP
Information on interfacing FormHandler forms and fields with a database.
Also see HTML::FormHandler::TraitFor::Model::DBIC.
.SH "Form Models"
.IX Header "Form Models"
For a database form, use a model base class that interfaces with the
database, such as HTML::FormHandler::Model::DBIC, which needs to
be installed as a separate package. There's also a sample 'object' model
in HTML::FormHandler::Model::Object, which will update a simple object.
.PP
When using a database model, form field values for the row are retrieved from
the database using the field 'accessor' attributes (defaults to field name)
as database class accessors.
.PP
FormHandler will use relationships to populate single and multiple
selection lists, and validate input. A 'single' relationship is processed
by HTML::FormHandler::Field::Compound. A 'has_many' relationship is
processed by HTML::FormHandler::Field::Repeatable.
.PP
Do not use database row method names, such as 'delete', as field names in
a database form.
.PP
You can pass in either the primary key or a row object to the form. If a
primary key (item_id) is passed in, you must also provide the schema.
The model will use the item_class (\s-1DBIC\s0 source name) to fetch the row from the
database. If you pass in a row object (item), the schema, item_class, and
item_id will be set from the row.
.PP
Executing \f(CW\*(C`$form\->process( item => $row, params => $params );\*(C'\fR will validate
the parameters and then update or create the database row object.
.SH "Fields that map to database relationships"
.IX Header "Fields that map to database relationships"
.SS "Select"
.IX Subsection "Select"
A select field will automatically retrieve a select list from the database,
if the proper column names are provided. Single selects handle 'belongs_to'
relationships, where the related table is used to construct a selection list
from the database.
.PP
See also HTML::FormHandler::Field::Select and 'lookup_options' in
HTML::FormHandler::TraitFor::Model::DBIC.
.SS "Multiple Select"
.IX Subsection "Multiple Select"
A multiple select is either a 'Select' with multiple => 1 set, or a field
of the 'Multiple' type. The name of a Multiple select which pulls options
from the database automatically should be the name of the 'many_to_many'
relationship. The 'value' of the field is derived from the 'has_many'
part of the relationship.
.PP
The primary key is used for the 'id' of the select. The 'label' column of
the select is assumed to be 'name'. If the label column has a different
name, it must be specified with 'label_column'.
.PP
Pertinent attributes:
.PP
.Vb 3
\&   label_column
\&   active_column
\&   sort_column
.Ve
.PP
See also HTML::FormHandler::Field::Select and
HTML::FormHandler::Model::DBIC.
.SS "Compound fields"
.IX Subsection "Compound fields"
A compound field represents a single relationship to another table.
Although most compound relations can be handled without providing a
primary key, in some circumstances you may need to provide a
PrimaryKey field, or add extra values in update_model.
.PP
See also HTML::FormHandler::Field::Compound.
.PP
The default for compound fields is that if all subfields are empty,
the value of the compound field is set to undef (null). For some types
of relations, you may want to set the 'not_nullable' flag to force
the field to contain all subfields anyway, such as when the related
rows are not deleted when empty. See test t/compound/empty.t for a
demonstration of the difference in output.
.SS "Repeatable fields"
.IX Subsection "Repeatable fields"
The 'Repeatable' field type allows you to update arrays of columns from related tables
easily. You will need to provide a 'PrimaryKey' hidden field in the
compound field contained in the Repeatable.
.PP
.Vb 5
\&  has_field \*(Aqaddresses\*(Aq => ( type => \*(AqRepeatable\*(Aq );
\&  has_field \*(Aqaddresses.address_id\*(Aq => ( type => \*(AqPrimaryKey\*(Aq );
\&  has_field \*(Aqaddresses.street\*(Aq;
\&  has_field \*(Aqaddresses.city\*(Aq;
\&  has_field \*(Aqaddresses.state\*(Aq;
.Ve
.PP
There are some complications with creating Repeatable elements (with
the PrimaryKey field set to undef) in a database and re-presenting the form.
See HTML::FormHandler::Field::Repeatable for more info.
.SH "Flags"
.IX Header "Flags"
.SS "writeonly"
.IX Subsection "writeonly"
Do not read the value from the 'item' when populating the form.
.SS "noupdate"
.IX Subsection "noupdate"
Do not update the database with this field, i.e. do not include it in
\&\f(CW\*(C`$form\->value\*(C'\fR.
.SH "Form generator"
.IX Header "Form generator"
A \s-1DBIC\s0 form generator is installed with the HTML::FormHandler::Model::DBIC
package. See HTML::FormHandler::Generator::DBIC.
.PP
There's also a role, HTML::FormHandler::TraitFor::DBICFields, that allows
simple form fields to be auto-generated from a \s-1DBIC\s0 result class.
.PP
.Vb 5
\&    my $form = HTML::FormHandler::Model::DBIC\->new_with_traits(
\&        traits => [\*(AqHTML::FormHandler::TraitFor::DBICFields\*(Aq],
\&        includes => [\*(Aqtitle\*(Aq, \*(Aqauthor\*(Aq ],
\&        field_list => [ \*(Aqsubmit\*(Aq => { type => \*(AqSubmit\*(Aq, value => \*(AqSave\*(Aq, order => 99 } ],
\&        item => $book );
.Ve
.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.