++ed by:
WKI
Author image Carl Franks
and 1 contributors

NAME

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

SYNOPSIS

Set a forms' default values from a DBIx::Class row object:

    my $row = $resultset->find( $id );
    
    $form->default_values( $row );

Update the database from a submitted form:

    if ( $form->submitted_and_valid ) {
        my $row = $resultset->find( $form->param('id') );
        
        $form->update( $row );
    }

METHODS

default_values

Arguments: $dbic_row, [\%config]

Return Value: $form

Set a form's default values from a DBIx::Class row.

Any form fields with a name matching a column name will have their default value set with the column value.

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

For the following DBIx::Class schemas:

    package MySchema::Book;
    use strict;
    use warnings;
    
    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 strict;
    use warnings;
    
    use base 'DBIx::Class';
    
    __PACKAGE__->load_components(qw/ Core /);
    
    __PACKAGE__->table("review");
    
    __PACKAGE__->add_columns(
        book   => { data_type => "INTEGER" },
        review => { data_type => "TEXT" },
    );
    
    __PACKAGE__->set_primary_key("book");
    
    __PACKAGE__->belongs_to( book => 'MySchema::Book' );
    
    1;

A suitable form for this would be:

    elements:
      - type: Hidden
        name: id
      
      - type: Text
        name: title
      
      - type: Block
        elements:
          - type: Text
            name: review

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.

If you want the related row deleted if a particular field is empty, set set $field->model_config->{delete_if_empty} to true.

    elements:
      - type: Hidden
        name: id
      
      - type: Text
        name: title
      
      - type: Block
        elements:
          - type: Text
            name: review
            model_config:
              dbic:
                delete_if_empty: 1

has_many and many_to_many relationships

To edit fields in related rows with has_many and many_to_many relationships, the fields must be placed within a Repeatable element. This will output a repetition of the entire block for each row returned. "increment_field_names" in HTML::FormFu::Element::Repeatable must be true (which is the default value).

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

If you want an extra, empty, copy of the block to be output, to allow the user to add a new row of data, set $block->model_config->{new_empty_row}. The value must be a column name, or arrayref of column names that must be filled in for the row to be added.

    ---
    element:
      - type: Repeatable
        nested_name: authors
        model_config:
          dbic: 
            new_empty_row: author
        
        elements:
          - type: Hidden
            name: id
          
          - type: Text
            name: author

If you want to add more than one new row you can use $block->model_config->{new_empty_row_multi} instead of $block->model_config->{new_empty_row}. To limit the maximum number of new rows put a range constraint on the count field.

    ---
    element:
      - type: Repeatable
        nested_name: authors
        model_config:
          dbic: 
            new_empty_row_multi: author
        
        elements:
          - type: Hidden
            name: id
          
          - type: Text
            name: author
            
      - type: Hidden
        name: count
        constraints: 
          - type: Range
            max: 3
        

If you want to provide a Checkbox or similar field, to allow the user to select whether given rows should be deleted (or, in the case of many_to_many relationships, unrelated), set $block->model_config->{delete_if_true} to the name of that field.

    ---
    element:
      - type: Repeatable
        nested_name: authors
        model_config:
          dbic:
            delete_if_true: delete
        
        elements:
          - type: Hidden
            name: id
          
          - type: Text
            name: author
          
          - type: Checkbox
            name: delete

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.

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:
            dbic:
              default_column: foo

non-column accessors

To make a form field correspond to a method in your DBIx::Class schema, that isn't a database column or relationship, set $field->model_config->{accessor}.

    ---
    element:
      - type: Text
        name: foo
        model_config:
          dbic:
            accessor: method_name

update

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

Return Value: $dbic_row

Update the database with the submitted form values. Uses update_or_insert.

See "default_values" for specifics about what relationships are supported and how to structure your forms.

Automatically creating a new row object

If you're using "update" to create a new row object, you don't need to create one yourself, as long as the DBIx::Class Schema is on the form "stash", and the ResultSet name is set in either the %config argument, the Form's "model_config" in HTML::FormFu, or the Block's "model_config" in HTML::FormFu (if "update" is called on a Block element).

If you're using Catalyst::Controller::HTML::FormFu, it can automatically place the schema on the Form's stash, by using the following Catalyst config (where MySchema is the name of your Catalyst model).

    'Controller::HTML::FormFu':
      model_stash:
        schema: MySchema

An example of setting the ResultSet name on a Form:

    ---
    model_config:
      resultset: FooTable

Note that if you still want to pass a %config argument, you must pass undef in place of the row:

    $form->update( undef, \%config );

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

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

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

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.