Provided by: libhtml-formfu-model-dbic-perl_1.00-1_all bug

NAME

       HTML::FormFu::Model::DBIC - Integrate HTML::FormFu with DBIx::Class

SYNOPSIS

       Example of typical use in a Catalyst controller:

           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('view', $book->id) );
                   return;
               }
               elsif ( !$form->submitted ) {

                   # use dbic row to set form's default values

                   $form->model->default_values( $book );
               }

               return;
           }

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 "schema".

       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.

       For example, if your model is named "MyApp::Model::Corp", you would set this (in
       Config::General format):

           <Controller::HTML::FormFu>
               <model_stash>
                   schema Corp
               </model_stash>
           </Controller::HTML::FormFu>

       Or if your app's config file is in YAML format:

           'Controller::HTML::FormFu':
               model_stash:
                   schema: Corp

METHODS

   default_values
       Arguments: $dbic_row, [\%config]

       Return Value: $form

           $form->model->default_values( $dbic_row );

       Set a form's default values from the database, to allow a user to edit them.

   update
       Arguments: [$dbic_row], [\%config]

       Return Value: $dbic_row

           $form->model->update( $dbic_row );

       Update the database with the submitted form values.

   create
       Arguments: [\%config]

       Return Value: $dbic_row

           my $dbic_row = $form->model->create( {resultset => 'Book'} );

       Like "update", but doesn't require a $dbic_row argument.

       You need to ensure the DBIC schema is available on the form stash - see "SYNOPSIS" for an
       example config.

       The "resultset" must be set either in the method arguments, or the form or block's
       "model_config".

       An example of setting the ResultSet name on a Form:

           ---
           model_config:
             resultset: FooTable

           elements:
             # [snip]

   options_from_model
       Populates a multi-valued field with values from the database.

       This method should not be called directly, but is called for you during "$form->process"
       by fields that inherit from HTML::FormFu::Element::_Group. This includes:

       HTML::FormFu::Element::Select
       HTML::FormFu::Element::Checkboxgroup
       HTML::FormFu::Element::Radiogroup
       HTML::FormFu::Element::ComboBox

       To use you must set the appropriate "resultset" on the element "model_config":

           element:
             - type: Select
               name: foo
               model_config:
                 resultset: TableClass

BUILDING FORMS

   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.

       For the following DBIx::Class schema:

           package MySchema::Book;
           use base 'DBIx::Class';

           __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;

       A suitable form for this might be:

           elements:
             - type: Text
               name: title

             - type: Text
               name: author

             - type: Textarea
               name: blurb

   might_have and has_one relationships
       Set field values from a related row with a "might_have" or "has_one" relationship by
       placing the fields within a Block (or any element that inherits from Block, such as
       Fieldset) with its "nested_name" in HTML::FormFu set to the relationship name.

       For the following DBIx::Class schemas:

           package MySchema::Book;
           use base 'DBIx::Class';

           __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 => 'MySchema::Review', 'book' );

           1;

           package MySchema::Review;
           use base 'DBIx::Class';

           __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 => 'MySchema::Book' );

           1;

       A suitable form for this would be:

           elements:
             - type: Text
               name: title

             - type: Block
               nested_name: review
               elements:
                 - type: Textarea
                   name: review_text

       For "might_have" and "has_one" 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.

       You can also set a "has_one" or "might_have" relationship using a multi value field like
       Select.

           elements:
             - type: Text
               name: title

             - type: Select
               nested: review
               model_config:
                 resultset: Review

       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 "Review" table and the foreign key do not match.

   has_many and many_to_many relationships
       The general principle is the same as for "might_have" and "has_one" above, except you
       should use a Repeatable element instead of a Block, and it needs to contain a Hidden field
       corresponding to the foreign key.

       The Repeatable block's nested_name must be set to the name of the relationship.

       The Repeable block's increment_field_names must be true (which is the default value).

       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 "$form->process" to ensure the form is rebuilt with the correct
       number of repetitions.

       To allow the user to add new related rows, either "empty_rows" or "new_rows_max" must be
       set - see "Config options for Repeatable blocks" below.

       For the following DBIx::Class schemas:

           package MySchema::Book;
           use base 'DBIx::Class';

           __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 => 'MySchema::Review', 'book' );

           1;

           package MySchema::Review;
           use base 'DBIx::Class';

           __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 => 'MySchema::Book' );

           1;

       A suitable form for this might be:

           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

   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.

           elements:
             - type: ComboBox
               name: author
               model_config:
                 resultset: Author
                 select_column: id
                 text_column: name

       The element name should match the relationship name.
       "$field->model_config->{select_column}" should match the related primary column.
       "$field->model_config->{text_column}" should match the related text column.

   many_to_many selection
       To select / deselect rows from a "many_to_many" relationship, you must use a multi-valued
       element, such as a Checkboxgroup or a Select with multiple set.

       The field's name must be set to the name of the "many_to_many" relationship.

       default_column

       If you want to search / associate the related table by a column other it's primary key,
       set "$field->model_config->{default_column}".

           ---
           element:
               - type: Checkboxgroup
                 name: authors
                 model_config:
                   default_column: foo

       link_values

       If you want to set columns on the link table you can do so if you add a "link_values"
       attribute to "model_config":

           ---
           element:
               - type: Checkboxgroup
                 name: authors
                 model_config:
                   link_values:
                     foo: bar

       additive

       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 "additive" in the
       "model_config".

           ---
           element:
               - type: Checkboxgroup
                 name: authors
                 model_config:
                   additive: 1
                   options_from_model: 0

       "options_from_model" is set to 0 because it will try to fetch all objects from the result
       class "Authors" if "model_config" is specified without a "resultset" attribute.)

COMMON ARGUMENTS

       The following items are supported in the optional "config" hash-ref argument to the
       methods default_values, update and create.

       base
           If you want the method to process a particular Block element, rather than the whole
           form, you can pass the element as a "base" argument.

               $form->default_values(
                   $row,
                   {
                       base => $formfu_element,
                   },
               );

       nested_base
           If you want the method to process a particular Block element by name, you can pass the
           name as an argument.

               $form->default_values(
                   $row,
                   {
                       nested_base => 'foo',
                   }'
               );

CONFIGURATION

   Config options for fields
       The following items are supported as "model_config" options on form fields.

       accessor
           If set, "accessor" will be used as a method-name accessor on the "DBIx::Class" row
           object, instead of using the field name.

       ignore_if_empty
           If the submitted value is blank, no attempt will be made to save it to the database.

       null_if_empty
           If the submitted value is blank, save it as NULL to the database. Normally an empty
           string is saved as NULL 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.

       delete_if_empty
           Useful for editing a "might_have" related row containing only one field.

           If the submitted value is blank, the related row is deleted.

           For the following DBIx::Class schemas:

               package MySchema::Book;
               use base 'DBIx::Class';

               __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 => 'MySchema::Review', 'book' );

               1;

               package MySchema::Review;
               use base 'DBIx::Class';

               __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 => 'MySchema::Book' );

               1;

           A suitable form for this would be:

               elements:
                 - type: Text
                   name: title

                 - type: Block
                   nested_name: review
                   elements:
                     - type: Text
                       name: review_text
                       model_config:
                         delete_if_empty: 1

       label
           To use a column value for a form field's label.

   Config options for fields within a Repeatable block
       delete_if_true
           Intended for use on a Checkbox field.

           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.

           An example of use might be:

               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: 'Delete Review?'
                       model_config:
                         delete_if_true: 1

           Note: make sure the name of this field does not clash with one of your
           DBIx::Class::Row method names (e.g. "delete") - see "CAVEATS".

   Config options for Repeatable blocks
       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 "empty_rows" to the number of extra repetitions
           you wish added to the end of the Repeatable block.

       new_rows_max
           Set to the maximum number of new rows that a Repeatable block is allowed to add.

           If not set, it will fallback to the value of "empty_rows".

   Config options for options_from_model
       The column used for the element values is set with the "model_config" value "id_column" -
       or if not set, the table's primary column is used.

           element:
             - type: Select
               name: foo
               model_config:
                 resultset: TableClass
                 id_column: pk_col

       The column used for the element labels is set with the "model_config" value "label_column"
       - or if not set, the first text/varchar column found in the table is used - or if one is
       not found, the "id_column" is used instead.

           element:
             - type: Select
               name: foo
               model_config:
                 resultset: TableClass
                 label_column: label_col

       To pass the database label values via the form's localization object, set "localize_label"

           element:
             - type: Select
               name: foo
               model_config:
                 localize_label: 1

       You can set a "condition", which will be passed as the 1st argument to "search" in
       DBIx::Class::ResultSet.

           element:
             - type: Select
               name: foo
               model_config:
                 resultset: TableClass
                 condition:
                   type: is_foo

       You can set a "condition_from_stash", which will be passed as the 1st argument to "search"
       in DBIx::Class::ResultSet.

       "key" is the column-name to be passed to search, and "stash_key" is the name of a key on
       the form stash from which the value to be passed to search is found.

           element:
             - type: Select
               name: foo
               model_config:
                 resultset: TableClass
                 condition_from_stash:
                   key: stash_key

       Is comparable to:

           $form->element({
               type => 'Select',
               name => 'foo',
               model_config => {
                   resultset => 'TableClass',
                   condition => {
                       key => $form->stash->{stash_key}
                   }
               }
           })

       You can set "attributes", which will be passed as the 2nd argument to "search" in
       DBIx::Class::ResultSet.

       ENUM Column Type

       If the field name matches (case-insensitive) a column name with type 'ENUM' and the Schema
       contains enum values in "$resultset->column_info($name)->{extra}{list}", the field's
       options will be populated with the enum values.

FAQ

   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.

           my $passwd = generate_passwd();

           $form->add_valid( passwd => $passwd );

           $form->model->update( $row );

       "add_valid" works for fieldnames that don't exist in the form.

   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.

         $field->model_config->{read_only} = 1;

         - Name: field
           model_config:
             read_only: 1

       See HTML::FormFu::Element::Label.

CAVEATS

       To ensure your column's inflators and deflators are called, we have to get / set values
       using their named methods, and not with "get_column" / "set_column".

       Because of this, beware of having column names which clash with DBIx::Class built-in
       method-names, such as "delete". - It will have obviously undesirable results!

REMOVED METHODS

   new_empty_row
       See "empty_rows" in "Config options for Repeatable blocks" instead.

   new_empty_row_multi
       See "new_rows_max" in "Config options for Repeatable blocks" instead.

   Range constraint
       See "empty_rows" in "Config options for Repeatable blocks" instead.

SUPPORT

       Project Page:

       <http://code.google.com/p/html-formfu/>

       Mailing list:

       <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>

       Mailing list archives:

       <http://lists.scsys.co.uk/pipermail/html-formfu/>

BUGS

       Please submit bug reports to the Debian Bug Tracker. You can use reportbug(1) to do so
       interactively. A list of reported bugs can be found at
       <http://bugs.debian.org/libhtml-formfu-perl>.

       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>.

GITHUB REPOSITORY

       This module's sourcecode is maintained in a git repository at
       <git://github.com/fireartist/HTML-FormFu-Model-DBIC.git>

       The project page is <https://github.com/fireartist/HTML-FormFu-Model-DBIC>

SEE ALSO

       HTML::FormFu, DBIx::Class, Catalyst::Controller::HTML::FormFu

AUTHOR

       Carl Franks

CONTRIBUTORS

       Based on the code of "DBIx::Class::HTML::FormFu", which was contributed to by:

       Adam Herzog

       Daisuke Maki

       Mario Minati

COPYRIGHT AND LICENSE

       Copyright (C) 2007 by Carl Franks

       Based on the original source code of DBIx::Class::HTMLWidget, copyright Thomas Klausner.

       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.