.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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::FormFu::Model::DBIC 3pm"
.TH HTML::FormFu::Model::DBIC 3pm "2021-01-05" "perl v5.32.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::FormFu::Model::DBIC \- Integrate HTML::FormFu with DBIx::Class
.SH "VERSION"
.IX Header "VERSION"
version 2.03
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Example of typical use in a Catalyst controller:
.PP
.Vb 2
\&    sub edit : Chained {
\&        my ( $self, $c ) = @_;
\&
\&        my $form = $c\->stash\->{form};
\&        my $book = $c\->stash\->{book};
\&
\&        if ( $form\->submitted_and_valid ) {
\&
\&            # update dbic row with submitted values from form
\&
\&            $form\->model\->update( $book );
\&
\&            $c\->response\->redirect( $c\->uri_for(\*(Aqview\*(Aq, $book\->id) );
\&            return;
\&        }
\&        elsif ( !$form\->submitted ) {
\&
\&            # use dbic row to set form\*(Aqs default values
\&
\&            $form\->model\->default_values( $book );
\&        }
\&
\&        return;
\&    }
.Ve
.SH "SETUP"
.IX Header "SETUP"
For the form object to be able to access your DBIx::Class schema, it needs
to be placed on the form stash, with the name \f(CW\*(C`schema\*(C'\fR.
.PP
This is easy if you're using Catalyst-Controller-HTML-FormFu, as you can
set this up to happen in your Catalyst app's config file.
.PP
For example, if your model is named \f(CW\*(C`MyApp::Model::Corp\*(C'\fR, you would set this
(in Config::General format):
.PP
.Vb 5
\&    <Controller::HTML::FormFu>
\&        <model_stash>
\&            schema Corp
\&        </model_stash>
\&    </Controller::HTML::FormFu>
.Ve
.PP
Or if your app's config file is in \s-1YAML\s0 format:
.PP
.Vb 3
\&    \*(AqController::HTML::FormFu\*(Aq:
\&        model_stash:
\&            schema: Corp
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "default_values"
.IX Subsection "default_values"
Arguments: \f(CW$dbic_row\fR, [\e%config]
.PP
Return Value: \f(CW$form\fR
.PP
.Vb 1
\&    $form\->model\->default_values( $dbic_row );
.Ve
.PP
Set a form's default values from the database, to allow a user to edit them.
.SS "update"
.IX Subsection "update"
Arguments: [$dbic_row], [\e%config]
.PP
Return Value: \f(CW$dbic_row\fR
.PP
.Vb 1
\&    $form\->model\->update( $dbic_row );
.Ve
.PP
Update the database with the submitted form values.
.SS "create"
.IX Subsection "create"
Arguments: [\e%config]
.PP
Return Value: \f(CW$dbic_row\fR
.PP
.Vb 1
\&    my $dbic_row = $form\->model\->create( {resultset => \*(AqBook\*(Aq} );
.Ve
.PP
Like \*(L"update\*(R", but doesn't require a \f(CW$dbic_row\fR argument.
.PP
You need to ensure the \s-1DBIC\s0 schema is available on the form stash \- see
\&\*(L"\s-1SYNOPSIS\*(R"\s0 for an example config.
.PP
The \f(CW\*(C`resultset\*(C'\fR must be set either in the method arguments, or the form or
block's \f(CW\*(C`model_config\*(C'\fR.
.PP
An example of setting the ResultSet name on a Form:
.PP
.Vb 3
\&    \-\-\-
\&    model_config:
\&      resultset: FooTable
\&
\&    elements:
\&      # [snip]
.Ve
.SS "options_from_model"
.IX Subsection "options_from_model"
Populates a multi-valued field with values from the database.
.PP
This method should not be called directly, but is called for you during
\&\f(CW\*(C`$form\->process\*(C'\fR by fields that inherit from
HTML::FormFu::Element::_Group. This includes:
.IP "HTML::FormFu::Element::Select" 4
.IX Item "HTML::FormFu::Element::Select"
.PD 0
.IP "HTML::FormFu::Element::Checkboxgroup" 4
.IX Item "HTML::FormFu::Element::Checkboxgroup"
.IP "HTML::FormFu::Element::Radiogroup" 4
.IX Item "HTML::FormFu::Element::Radiogroup"
.IP "HTML::FormFu::Element::ComboBox" 4
.IX Item "HTML::FormFu::Element::ComboBox"
.PD
.PP
To use you must set the appropriate \f(CW\*(C`resultset\*(C'\fR on the element \f(CW\*(C`model_config\*(C'\fR:
.PP
.Vb 5
\&    element:
\&      \- type: Select
\&        name: foo
\&        model_config:
\&          resultset: TableClass
.Ve
.SH "BUILDING FORMS"
.IX Header "BUILDING FORMS"
.SS "single table"
.IX Subsection "single table"
To edit the values in a row with no related rows, the field names simply have
to correspond to the database column names.
.PP
For the following DBIx::Class schema:
.PP
.Vb 2
\&    package MySchema::Book;
\&    use base \*(AqDBIx::Class\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->load_components(qw/ Core /);
\&
\&    _\|_PACKAGE_\|_\->table("book");
\&
\&    _\|_PACKAGE_\|_\->add_columns(
\&        id     => { data_type => "INTEGER" },
\&        title  => { data_type => "TEXT" },
\&        author => { data_type => "TEXT" },
\&        blurb  => { data_type => "TEXT" },
\&    );
\&
\&    _\|_PACKAGE_\|_\->set_primary_key("id");
\&
\&    1;
.Ve
.PP
A suitable form for this might be:
.PP
.Vb 3
\&    elements:
\&      \- type: Text
\&        name: title
\&
\&      \- type: Text
\&        name: author
\&
\&      \- type: Textarea
\&        name: blurb
.Ve
.SS "might_have and has_one relationships"
.IX Subsection "might_have and has_one relationships"
Set field values from a related row with a \f(CW\*(C`might_have\*(C'\fR or \f(CW\*(C`has_one\*(C'\fR
relationship by placing the fields within a
Block (or any element that inherits from
Block, such as Fieldset) with its
\&\*(L"nested_name\*(R" in HTML::FormFu set to the relationship name.
.PP
For the following DBIx::Class schemas:
.PP
.Vb 2
\&    package MySchema::Book;
\&    use base \*(AqDBIx::Class\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->load_components(qw/ Core /);
\&
\&    _\|_PACKAGE_\|_\->table("book");
\&
\&    _\|_PACKAGE_\|_\->add_columns(
\&        id    => { data_type => "INTEGER" },
\&        title => { data_type => "TEXT" },
\&    );
\&
\&    _\|_PACKAGE_\|_\->set_primary_key("id");
\&
\&    _\|_PACKAGE_\|_\->might_have( review => \*(AqMySchema::Review\*(Aq, \*(Aqbook\*(Aq );
\&
\&    1;
\&
\&
\&    package MySchema::Review;
\&    use base \*(AqDBIx::Class\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->load_components(qw/ Core /);
\&
\&    _\|_PACKAGE_\|_\->table("review");
\&
\&    _\|_PACKAGE_\|_\->add_columns(
\&        id          => { data_type => "INTEGER" },
\&        book        => { data_type => "INTEGER", is_nullable => 1 },
\&        review_text => { data_type => "TEXT" },
\&    );
\&
\&    _\|_PACKAGE_\|_\->set_primary_key("book");
\&
\&    _\|_PACKAGE_\|_\->belongs_to( book => \*(AqMySchema::Book\*(Aq );
\&
\&    1;
.Ve
.PP
A suitable form for this would be:
.PP
.Vb 3
\&    elements:
\&      \- type: Text
\&        name: title
\&
\&      \- type: Block
\&        nested_name: review
\&        elements:
\&          \- type: Textarea
\&            name: review_text
.Ve
.PP
For \f(CW\*(C`might_have\*(C'\fR and \f(CW\*(C`has_one\*(C'\fR relationships, you generally shouldn't need
to have a field for the related table's primary key, as DBIx::Class will
handle retrieving the correct row automatically.
.PP
You can also set a \f(CW\*(C`has_one\*(C'\fR or \f(CW\*(C`might_have\*(C'\fR relationship using a multi value
field like Select.
.PP
.Vb 3
\&    elements:
\&      \- type: Text
\&        name: title
\&
\&      \- type: Select
\&        nested: review
\&        model_config:
\&          resultset: Review
.Ve
.PP
This will load all reviews into the select field. If you select a review from
that list, a current relationship to a review is removed and the new one is
added. This requires that the primary key of the \f(CW\*(C`Review\*(C'\fR table and the
foreign key do not match.
.SS "has_many and many_to_many relationships"
.IX Subsection "has_many and many_to_many relationships"
The general principle is the same as for \f(CW\*(C`might_have\*(C'\fR and \f(CW\*(C`has_one\*(C'\fR above,
except you should use a Repeatable
element instead of a Block, and it needs to contain a
Hidden field corresponding to the primary key
of the related table.
.PP
The Repeatable block's
nested_name must be set to the
name of the relationship.
.PP
The Repeable block's
increment_field_names
must be true (which is the default value).
.PP
The Repeable block's
counter_name must be set to
the name of a Hidden field, which is placed
outside of the Repeatable block.
This field is used to store a count of the number of repetitions of the
Repeatable block were created.
When the form is submitted, this value is used during \f(CW\*(C`$form\->process\*(C'\fR
to ensure the form is rebuilt with the correct number of repetitions.
.PP
To allow the user to add new related rows, either \f(CW\*(C`empty_rows\*(C'\fR or
\&\f(CW\*(C`new_rows_max\*(C'\fR must be set \- see \*(L"Config options for Repeatable blocks\*(R"
below.
.PP
For the following DBIx::Class schemas:
.PP
.Vb 2
\&    package MySchema::Book;
\&    use base \*(AqDBIx::Class\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->load_components(qw/ Core /);
\&
\&    _\|_PACKAGE_\|_\->table("book");
\&
\&    _\|_PACKAGE_\|_\->add_columns(
\&        id    => { data_type => "INTEGER" },
\&        title => { data_type => "TEXT" },
\&    );
\&
\&    _\|_PACKAGE_\|_\->set_primary_key("id");
\&
\&    _\|_PACKAGE_\|_\->has_many( review => \*(AqMySchema::Review\*(Aq, \*(Aqbook\*(Aq );
\&
\&    1;
\&
\&
\&    package MySchema::Review;
\&    use base \*(AqDBIx::Class\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->load_components(qw/ Core /);
\&
\&    _\|_PACKAGE_\|_\->table("review");
\&
\&    _\|_PACKAGE_\|_\->add_columns(
\&        book        => { data_type => "INTEGER" },
\&        review_text => { data_type => "TEXT" },
\&    );
\&
\&    _\|_PACKAGE_\|_\->set_primary_key("book");
\&
\&    _\|_PACKAGE_\|_\->belongs_to( book => \*(AqMySchema::Book\*(Aq );
\&
\&    1;
.Ve
.PP
A suitable form for this might be:
.PP
.Vb 3
\&    elements:
\&      \- type: Text
\&        name: title
\&
\&      \- type: Hidden
\&        name: review_count
\&
\&      \- type: Repeatable
\&        nested_name: review
\&        counter_name: review_count
\&        model_config:
\&          empty_rows: 1
\&        elements:
\&          \- type: Hidden
\&            name: book
\&
\&          \- type: Textarea
\&            name: review_text
.Ve
.SS "belongs_to relationships"
.IX Subsection "belongs_to relationships"
Belongs-to relationships can be edited / created with a ComboBox element.
If the user selects a value with the Select field, the belongs-to will be set
to an already-existing row in the related table.
If the user enters a value into the Text field, the belongs-to will be set
using a newly-created row in the related table.
.PP
.Vb 7
\&    elements:
\&      \- type: ComboBox
\&        name: author
\&        model_config:
\&          resultset: Author
\&          select_column: id
\&          text_column: name
.Ve
.PP
The element name should match the relationship name.
\&\f(CW\*(C`$field\->model_config\->{select_column}\*(C'\fR should match the related primary
column.
\&\f(CW\*(C`$field\->model_config\->{text_column}\*(C'\fR should match the related text
column.
.SS "many_to_many selection"
.IX Subsection "many_to_many selection"
To select / deselect rows from a \f(CW\*(C`many_to_many\*(C'\fR relationship, you must use
a multi-valued element, such as a
Checkboxgroup or a
Select with
multiple set.
.PP
The field's name must be set to the
name of the \f(CW\*(C`many_to_many\*(C'\fR relationship.
.PP
\fIdefault_column\fR
.IX Subsection "default_column"
.PP
If you want to search / associate the related table by a column other it's
primary key, set \f(CW\*(C`$field\->model_config\->{default_column}\*(C'\fR.
.PP
.Vb 6
\&    \-\-\-
\&    element:
\&        \- type: Checkboxgroup
\&          name: authors
\&          model_config:
\&            default_column: foo
.Ve
.PP
\fIlink_values\fR
.IX Subsection "link_values"
.PP
If you want to set columns on the link table you can do so if you add a
\&\f(CW\*(C`link_values\*(C'\fR attribute to \f(CW\*(C`model_config\*(C'\fR:
.PP
.Vb 7
\&    \-\-\-
\&    element:
\&        \- type: Checkboxgroup
\&          name: authors
\&          model_config:
\&            link_values:
\&              foo: bar
.Ve
.PP
\fIadditive\fR
.IX Subsection "additive"
.PP
The default implementation will first remove all related objects and set the
new ones (see <http://search.cpan.org/perldoc?DBIx::Class::Relationship::Base#set_$rel>).
If you want to add the selected objects to the current set of objects
set \f(CW\*(C`additive\*(C'\fR in the \f(CW\*(C`model_config\*(C'\fR.
.PP
.Vb 7
\&    \-\-\-
\&    element:
\&        \- type: Checkboxgroup
\&          name: authors
\&          model_config:
\&            additive: 1
\&            options_from_model: 0
.Ve
.PP
\&\*(L"options_from_model\*(R" is set to \f(CW0\fR because it will try to fetch
all objects from the result class \f(CW\*(C`Authors\*(C'\fR if \f(CW\*(C`model_config\*(C'\fR is specified
without a \f(CW\*(C`resultset\*(C'\fR attribute.)
.SH "COMMON ARGUMENTS"
.IX Header "COMMON ARGUMENTS"
The following items are supported in the optional \f(CW\*(C`config\*(C'\fR hash-ref argument
to the methods default_values, update and create.
.IP "base" 4
.IX Item "base"
If you want the method to process a particular Block element, rather than the
whole form, you can pass the element as a \f(CW\*(C`base\*(C'\fR argument.
.Sp
.Vb 6
\&    $form\->default_values(
\&        $row,
\&        {
\&            base => $formfu_element,
\&        },
\&    );
.Ve
.IP "nested_base" 4
.IX Item "nested_base"
If you want the method to process a particular Block element by
name, you can pass the name as an argument.
.Sp
.Vb 6
\&    $form\->default_values(
\&        $row,
\&        {
\&            nested_base => \*(Aqfoo\*(Aq,
\&        }\*(Aq
\&    );
.Ve
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.SS "Config options for fields"
.IX Subsection "Config options for fields"
The following items are supported as \f(CW\*(C`model_config\*(C'\fR options on form fields.
.IP "accessor" 4
.IX Item "accessor"
If set, \f(CW\*(C`accessor\*(C'\fR will be used as a method-name accessor on the
\&\f(CW\*(C`DBIx::Class\*(C'\fR row object, instead of using the field name.
.IP "ignore_if_empty" 4
.IX Item "ignore_if_empty"
If the submitted value is blank, no attempt will be made to save it to the database.
.IP "null_if_empty" 4
.IX Item "null_if_empty"
If the submitted value is blank, save it as \s-1NULL\s0 to the database. Normally an empty string is saved as \s-1NULL\s0 when its corresponding field is numeric, and as an empty string when its corresponding field is a text field. This option is useful for changing the default behavior for text fields.
.IP "delete_if_empty" 4
.IX Item "delete_if_empty"
Useful for editing a \*(L"might_have\*(R" related row containing only one field.
.Sp
If the submitted value is blank, the related row is deleted.
.Sp
For the following DBIx::Class schemas:
.Sp
.Vb 2
\&    package MySchema::Book;
\&    use base \*(AqDBIx::Class\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->load_components(qw/ Core /);
\&
\&    _\|_PACKAGE_\|_\->table("book");
\&
\&    _\|_PACKAGE_\|_\->add_columns(
\&        id    => { data_type => "INTEGER" },
\&        title => { data_type => "TEXT" },
\&    );
\&
\&    _\|_PACKAGE_\|_\->set_primary_key("id");
\&
\&    _\|_PACKAGE_\|_\->might_have( review => \*(AqMySchema::Review\*(Aq, \*(Aqbook\*(Aq );
\&
\&    1;
\&
\&
\&    package MySchema::Review;
\&    use base \*(AqDBIx::Class\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->load_components(qw/ Core /);
\&
\&    _\|_PACKAGE_\|_\->table("review");
\&
\&    _\|_PACKAGE_\|_\->add_columns(
\&        book        => { data_type => "INTEGER" },
\&        review_text => { data_type => "TEXT" },
\&    );
\&
\&    _\|_PACKAGE_\|_\->set_primary_key("book");
\&
\&    _\|_PACKAGE_\|_\->belongs_to( book => \*(AqMySchema::Book\*(Aq );
\&
\&    1;
.Ve
.Sp
A suitable form for this would be:
.Sp
.Vb 3
\&    elements:
\&      \- type: Text
\&        name: title
\&
\&      \- type: Block
\&        nested_name: review
\&        elements:
\&          \- type: Text
\&            name: review_text
\&            model_config:
\&              delete_if_empty: 1
.Ve
.IP "label" 4
.IX Item "label"
To use a column value for a form field's
label.
.SS "Config options for fields within a Repeatable block"
.IX Subsection "Config options for fields within a Repeatable block"
.IP "delete_if_true" 4
.IX Item "delete_if_true"
Intended for use on a Checkbox field.
.Sp
If the checkbox is checked, the following occurs: for a has-many relationship,
the related row is deleted; for a many-to-many relationship, the relationship
link is removed.
.Sp
An example of use might be:
.Sp
.Vb 3
\&    elements:
\&      \- type: Text
\&        name: title
\&
\&      \- type: Hidden
\&        name: review_count
\&
\&      \- type: Repeatable
\&        nested_name: review
\&        counter_name: review_count
\&        elements:
\&          \- type: Hidden
\&            name: book
\&
\&          \- type: Textarea
\&            name: review_text
\&
\&          \- type: Checkbox
\&            name: delete_review
\&            label: \*(AqDelete Review?\*(Aq
\&            model_config:
\&              delete_if_true: 1
.Ve
.Sp
Note: make sure the name of this field does not clash with one of your
DBIx::Class::Row method names (e.g. \*(L"delete\*(R") \- see \*(L"\s-1CAVEATS\*(R"\s0.
.SS "Config options for Repeatable blocks"
.IX Subsection "Config options for Repeatable blocks"
.IP "empty_rows" 4
.IX Item "empty_rows"
For a Repeatable block corresponding to a has-many or many-to-many
relationship, to allow the user to insert new rows, set \f(CW\*(C`empty_rows\*(C'\fR to
the number of extra repetitions you wish added to the end of the Repeatable
block.
.IP "new_rows_max" 4
.IX Item "new_rows_max"
Set to the maximum number of new rows that a Repeatable block is allowed to
add.
.Sp
If not set, it will fallback to the value of \f(CW\*(C`empty_rows\*(C'\fR.
.SS "Config options for options_from_model"
.IX Subsection "Config options for options_from_model"
The column used for the element values is set with the \f(CW\*(C`model_config\*(C'\fR
value \f(CW\*(C`id_column\*(C'\fR \- or if not set, the table's primary column is used.
.PP
.Vb 6
\&    element:
\&      \- type: Select
\&        name: foo
\&        model_config:
\&          resultset: TableClass
\&          id_column: pk_col
.Ve
.PP
The column used for the element labels is set with the \f(CW\*(C`model_config\*(C'\fR
value \f(CW\*(C`label_column\*(C'\fR \- or if not set, the first text/varchar column found
in the table is used \- or if one is not found, the \f(CW\*(C`id_column\*(C'\fR is used
instead.
.PP
.Vb 6
\&    element:
\&      \- type: Select
\&        name: foo
\&        model_config:
\&          resultset: TableClass
\&          label_column: label_col
.Ve
.PP
To pass the database label values via the form's localization object, set
\&\f(CW\*(C`localize_label\*(C'\fR
.PP
.Vb 5
\&    element:
\&      \- type: Select
\&        name: foo
\&        model_config:
\&          localize_label: 1
.Ve
.PP
You can set a \f(CW\*(C`condition\*(C'\fR, which will be passed as the 1st argument to
\&\*(L"search\*(R" in DBIx::Class::ResultSet.
.PP
.Vb 7
\&    element:
\&      \- type: Select
\&        name: foo
\&        model_config:
\&          resultset: TableClass
\&          condition:
\&            type: is_foo
.Ve
.PP
You can set a \f(CW\*(C`condition_from_stash\*(C'\fR, which will be passed as the 1st argument to
\&\*(L"search\*(R" in DBIx::Class::ResultSet.
.PP
\&\f(CW\*(C`key\*(C'\fR is the column-name to be passed to
search,
and \f(CW\*(C`stash_key\*(C'\fR is the name of a key on the form stash
from which the value to be passed to search
is found.
.PP
.Vb 7
\&    element:
\&      \- type: Select
\&        name: foo
\&        model_config:
\&          resultset: TableClass
\&          condition_from_stash:
\&            key: stash_key
.Ve
.PP
Is comparable to:
.PP
.Vb 10
\&    $form\->element({
\&        type => \*(AqSelect\*(Aq,
\&        name => \*(Aqfoo\*(Aq,
\&        model_config => {
\&            resultset => \*(AqTableClass\*(Aq,
\&            condition => {
\&                key => $form\->stash\->{stash_key}
\&            }
\&        }
\&    })
.Ve
.PP
If the value in the stash is nested in a data-structure, you can access it by
setting \f(CW\*(C`expand_stash_dots\*(C'\fR. As you can see in the example below, it
automatically handles calling methods on objects, accessing hash-keys on
hash-references, and accessing array-slots on array references.
.PP
.Vb 8
\&    element:
\&      \- type: Select
\&        name: foo
\&        model_config:
\&          resultset: TableClass
\&          condition_from_stash:
\&            key: foo.bar.0
\&          expand_stash_dots: 1
.Ve
.PP
Is comparable to:
.PP
.Vb 10
\&    $form\->element({
\&        type => \*(AqSelect\*(Aq,
\&        name => \*(Aqfoo\*(Aq,
\&        model_config => {
\&            resultset => \*(AqTableClass\*(Aq,
\&            condition => {
\&                key => $form\->stash\->{foo}\->bar\->[0];
\&            }
\&        }
\&    })
\&    # Where stash returns a hashref.
\&    # The \*(Aqfoo\*(Aq hash\-key returns an object.
\&    # The object\-method \*(Aqbar\*(Aq returns an arrayref.
\&    # The first array slot returns the value used in the query.
.Ve
.PP
You can set \f(CW\*(C`attributes\*(C'\fR, which will be passed as the 2nd argument to
\&\*(L"search\*(R" in DBIx::Class::ResultSet.
.PP
\fI\s-1ENUM\s0 Column Type\fR
.IX Subsection "ENUM Column Type"
.PP
If the field name matches (case-insensitive) a column name with type '\s-1ENUM\s0'
and the Schema contains enum values in
\&\f(CW\*(C`$resultset\->column_info($name)\->{extra}{list}\*(C'\fR, the field's options
will be populated with the enum values.
.SH "FAQ"
.IX Header "FAQ"
.SS "Add extra values not in the form"
.IX Subsection "Add extra values not in the form"
To update values to the database which weren't submitted to the form,
you can first add them to the form with add_valid.
.PP
.Vb 1
\&    my $passwd = generate_passwd();
\&
\&    $form\->add_valid( passwd => $passwd );
\&
\&    $form\->model\->update( $row );
.Ve
.PP
\&\f(CW\*(C`add_valid\*(C'\fR works for fieldnames that don't exist in the form.
.SS "Set a field read only"
.IX Subsection "Set a field read only"
You can make a field read only. The value of such fields cannot be changed by
the user even if they submit a value for it.
.PP
.Vb 1
\&  $field\->model_config\->{read_only} = 1;
\&
\&  \- Name: field
\&    model_config:
\&      read_only: 1
.Ve
.PP
See HTML::FormFu::Element::Label.
.SH "CAVEATS"
.IX Header "CAVEATS"
To ensure your column's inflators and deflators are called, we have to
get / set values using their named methods, and not with \f(CW\*(C`get_column\*(C'\fR /
\&\f(CW\*(C`set_column\*(C'\fR.
.PP
Because of this, beware of having column names which clash with DBIx::Class
built-in method-names, such as \f(CW\*(C`delete\*(C'\fR. \- It will have obviously
undesirable results!
.SH "REMOVED METHODS"
.IX Header "REMOVED METHODS"
.SS "new_empty_row"
.IX Subsection "new_empty_row"
See \f(CW\*(C`empty_rows\*(C'\fR in \*(L"Config options for Repeatable blocks\*(R" instead.
.SS "new_empty_row_multi"
.IX Subsection "new_empty_row_multi"
See \f(CW\*(C`new_rows_max\*(C'\fR in \*(L"Config options for Repeatable blocks\*(R" instead.
.SS "Range constraint"
.IX Subsection "Range constraint"
See \f(CW\*(C`empty_rows\*(C'\fR in \*(L"Config options for Repeatable blocks\*(R" instead.
.SH "SUPPORT"
.IX Header "SUPPORT"
Project Page:
.PP
<http://code.google.com/p/html\-formfu/>
.PP
Mailing list:
.PP
<http://lists.scsys.co.uk/cgi\-bin/mailman/listinfo/html\-formfu>
.PP
Mailing list archives:
.PP
<http://lists.scsys.co.uk/pipermail/html\-formfu/>
.SH "BUGS"
.IX Header "BUGS"
Please submit bug reports to the Debian Bug Tracker. You can use
\&\fBreportbug\fR\|(1) to do so interactively. A list of reported bugs can be found
at <http://bugs.debian.org/libhtml\-formfu\-perl>.
.PP
For upstream bug reports / feature requests look at
<http://code.google.com/p/html\-formfu/issues/list> (preferred) or
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML\-FormFu>.
.SH "GITHUB REPOSITORY"
.IX Header "GITHUB REPOSITORY"
This module's sourcecode is maintained in a git repository at
<git://github.com/fireartist/HTML\-FormFu\-Model\-DBIC.git>
.PP
The project page is <https://github.com/fireartist/HTML\-FormFu\-Model\-DBIC>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
HTML::FormFu, DBIx::Class, Catalyst::Controller::HTML::FormFu
.SH "AUTHOR"
.IX Header "AUTHOR"
Carl Franks
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Based on the code of \f(CW\*(C`DBIx::Class::HTML::FormFu\*(C'\fR, which was contributed to
by:
.PP
Adam Herzog
.PP
Daisuke Maki
.PP
Mario Minati
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 by Carl Franks
.PP
Based on the original source code of DBIx::Class::HTMLWidget, copyright
Thomas Klausner.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.