/ 
Form-Processor-Model-DBIC-0.10001
River stage zero No dependents
/ Form::Processor::Model::DBIC

NAME

Form::Processor::Model::DBIC - Model class for Form Processor using DBIx::Class

SYNOPSIS

You need to create a form class, templates, and call F::P from a controller.

Create a Form, subclassed from Form::Processor::Model::DBIC

package MyApp:Form::User;
use strict;
use base 'Form::Processor::Model::DBIC';

# Associate this form with a DBIx::Class result class
sub object_class { 'User' } # Where 'User' is the DBIC source_name 

# Define the fields that this form will operate on
# Field names must be column or relationship names in your
# DBIx::Class result class
sub profile {
    return {
        fields => {
            name        => {
               type => 'Text',
               label => 'Name:',
               required => 1,
               noupdate => 1,
            },
            age         => {
                type => 'PosInteger',
                label    => 'Age:',
                required => 1,
            },
            sex         => {
                type => 'Select',
                label => 'Gender:',
                required => 1,
            },
            birthdate   => '+MyApp::Field::Date', # customized field class
            hobbies     =>  {
                type => 'Multiple',
                size => 5,
            },
            address     => 'Text',
            city        => 'Text',
            state       => 'Select',
        },

        dependency => [
            ['address', 'city', 'state'],
        ],
    };

Then in your template:

For an input field:

<p>
[% f = form.field('address') %]
<label class="label" for="[% f.name %]">[% f.label || f.name %]</label>
<input type="text" name="[% f.name %]" id="[% f.name %]">
</p>

For a select list provide a relationship name as the field name, or provide an options_<field_name> subroutine in the form. (field attributes: sort_order, label_column, active_column). TT example:

<p>
[% f = form.field('sex') %]
<label class="label" for="[% f.name %]">[% f.label || f.name %]</label>
<select name="[% f.name %]">
  [% FOR option IN f.options %]
    <option value="[% option.value %]" [% IF option.value == f.value %]selected="selected"[% END %]>[% option.label | html %]</option>
  [% END %] 
</select>
</p>

For a complex, widget-based TT setup, see the examples directory in the Catalyst::Plugin::Form::Processor CPAN download.

Then in a Catalyst controller (with Catalyst::Controller::Form::Processor):

package MyApp::Controller::User;
use strict;
use warnings;
use base 'Catalyst::Controller::Form::Processor';

# Create or edit
sub edit : Local {
    my ( $self, $c, $user_id ) = @_;
    $c->stash->{template} = 'user/edit.tt'; 
    # Validate and insert/update database. Args = pk, form name
    return unless $self->update_from_form( $user_id, 'User' );
    # Form validated.
    $c->stash->{user} = $c->stash->{form}->item;
    $c->res->redirect($c->uri_for('profile'));
}

With the Catalyst controller the schema is set from the model_name config options, ($c->model($model_name)...), but it can also be set by passing in the schema on "new", or setting with $form->schema($schema). You can also set a config values for whether or not to use FillInForm, and the form namespace.

DESCRIPTION

This DBIC model will save form fields automatically to the database, will retrieve selection lists from the database (with type => 'Select' and a fieldname containing a single relationship, or type => 'Multiple' and a many_to_many pseudo-relationship), and will save the selected values (one value for 'Select', multiple values in a mapping table for a 'Multiple' field).

This package includes a working example using a SQLite database and a number of forms. The templates are straightforward and unoptimized to make it easier to see what they're doing.

METHODS

schema

The schema method is primarily intended for non-Catalyst users, so that they can pass in their DBIx::Class schema object.

update_from_form

my $validated = $form->update_from_form( $parameter_hash );

This is not the same as the routine called with $self->update_from_form. That is a Catalyst plugin routine that calls this one. This routine updates or creates the object from values in the form.

All fields that refer to columns and have changed will be updated. Field names that are a single relationship will be updated. Any field names that are related to the class by "many_to_many" are assumed to have a mapping table and will be updated. Validation is run unless validation has already been run. ($form->clear might need to be called if the $form object stays in memory between requests.)

The actual update is done in the update_model method. Your form class can override that method (but don't forget to call SUPER) if you wish to do additional database inserts or updates. This is useful when a single form updates multiple tables, or there are secondary tables to update.

Returns false if form does not validate, otherwise returns 1. Very likely dies on database errors.

model_validate

The place to put validation that requires database-specific lookups. Subclass this method in your form.

update_model

This is where the database row is updated. If you want to do some extra database processing (such as updating a related table) this is the method to subclass in your form.

This routine allows the use of non-database (non-column, non-relationship) accessors in your result source class. It identifies form fields as 1) column, 2) relationship, 3) other. Column and other fields are processed and update is called on the row. Then relationships are processed.

If the row doesn't exist (no primary key or row object was passed in), then a row is created using "create" and the fields identified as columns passed in a hashref, followed by "other" fields and relationships.

guess_field_type

This subroutine is only called for "auto" fields, defined like: return { auto_required => ['name', 'age', 'sex', 'birthdate'], auto_optional => ['hobbies', 'address', 'city', 'state'], };

Pass in a column and it will guess the field type and return it.

Currently returns: DateTimeDMYHM - for a has_a relationship that isa DateTime Select - for a has_a relationship Multiple - for a has_many

otherwise: DateTimeDMYHM - if the field ends in _time Text - otherwise

Subclass this method to do your own field type assignment based on column types. This routine returns either an array or type string.

lookup_options

This method is used with "Single" and "Multiple" field select lists ("single", "filter", and "multi" relationships). It returns an array reference of key/value pairs for the column passed in. The column name defined in $field->label_column will be used as the label. The default label_column is "name". The labels are sorted by Perl's cmp sort.

If there is an "active" column then only active values are included, except if the form (item) has currently selected the inactive item. This allows existing records that reference inactive items to still have those as valid select options. The inactive labels are formatted with brackets to indicate in the select list that they are inactive.

The active column name is determined by calling: $active_col = $form->can( 'active_column' ) ? $form->active_column : $field->active_column;

This allows setting the name of the active column globally if your tables are consistantly named (all lookup tables have the same column name to indicate they are active), or on a per-field basis.

The column to use for sorting the list is specified with "sort_order". The currently selected values in a Multiple list are grouped at the top (by the Multiple field class).

init_value

This method returns a field's value (for $field->value) with either a scalar or an array ref from the object stored in $form->item.

This method is not called if a method "init_value_$field_name" is found in the form class - that method is called instead. This allows overriding specific fields in your form class.

validate_unique

For fields that are marked "unique", checks the database for uniqueness.

arraryref:
     unique => ['user_id', 'username']

or hashref:
     unique => {
         username => 'That username is already taken',
     }

init_item

This is called first time $form->item is called. If using the Catalyst plugin, it sets the DBIx::Class schema from the Catalyst context, and the model specified as the first part of the object_class in the form. If not using Catalyst, it uses the "schema" passed in on "new".

It then does:

return $self->resultset->find( $self->item_id );

It also validates that the item id matches /^\d+$/. Override this method in your form class (or form base class) if your ids do not match that pattern.

If a database row for the item_id is not found, item_id will be set to undef.

init_schema

Initializes the DBIx::Class schema. User may override. Non-Catalyst users should pass schema in on new: $my_form_class->new(item_id => $id, schema => $schema)

source

Returns a DBIx::Class::ResultSource object for this Result Class.

resultset

This method returns a resultset from the "object_class" specified in the form, or from the foreign class that is retrieved from a relationship.

build_form and _build_fields

These methods from Form::Processor are subclassed here to allow combining "required" and "optional" lists in one "fields" list, with "required" set like other field attributes.

SEE ALSO

Form::Processor Form::Processor::Field Form::Processor::Model::CDBI Catalyst::Controller:Form::Processor Rose::Object

AUTHOR

Gerda Shank, gshank@cpan.org

CONTRIBUTORS

Based on Form::Processor::Model::CDBI written by Bill Moseley.

LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.