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.

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

 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.

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 bugs / feature requests to
   <http://code.google.com/p/html-formfu/issues/list> (preferred) or
   <http://rt.perl.org>.

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.