Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

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( $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( $row );

Update the database with the submitted form values.

create

Arguments: [\%config]

Return Value: $dbic_row

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

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 simple 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 rebuild 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

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.

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

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 arguement to "search" in DBIx::Class::ResultSet.

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

You can set attributes, which will be passed as the 2nd arguement 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.

DEPRECATED

new_empty_row

Is deprecated and provided only for backwards compatability. Will be removed at some point in the future.

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

new_empty_row_multi

Is deprecated and provided only for backwards compatability. Will be removed at some point in the future.

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

Range constraint

The suggestion to use a Range constraint on the count field to limit the number of repetitions of a Repeatable block, has been withdrawn.

This was only useful in the case that there were no initial rows to be edited, otherwise the max() value could not be known ahead of time.

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

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!

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.

SUBVERSION REPOSITORY

The publicly viewable subversion code repository is at http://html-formfu.googlecode.com/svn/trunk/HTML-FormFu-Model-DBIC.

If you wish to contribute, you'll need a GMAIL email address. Then just ask on the mailing list for commit access.

If you wish to contribute but for some reason really don't want to sign up for a GMAIL account, please post patches to the mailing list (although you'll have to wait for someone to commit them).

If you have commit permissions, use the HTTPS repository url: https://html-formfu.googlecode.com/svn/trunk/HTML-FormFu-Model-DBIC

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

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.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 1347:: '=item' outside of any '=over'
Around line 1360:: You forgot a '=back' before '=head1'

To install HTML::FormFu::Model::DBIC, copy and paste the appropriate command in to your terminal.

cpanm

cpanm HTML::FormFu::Model::DBIC

CPAN shell

perl -MCPAN -e shell
install HTML::FormFu::Model::DBIC

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

SYNOPSIS

SETUP

METHODS

default_values

update

create

options_from_model

BUILDING FORMS

single table

might_have and has_one relationships

has_many and many_to_many relationships

many_to_many selection

COMMON ARGUMENTS

CONFIGURATION

Config options for fields

Config options for fields within a Repeatable block

Config options for Repeatable blocks

Config options for options_from_model

FAQ

Add extra values not in the form

Set a field read only

DEPRECATED

new_empty_row

new_empty_row_multi

Range constraint

CAVEATS

SUPPORT

BUGS

SUBVERSION REPOSITORY

SEE ALSO

AUTHOR

CONTRIBUTORS

COPYRIGHT AND LICENSE

Module Install Instructions