NAME
HTML::FormHandler::Model::DBIC - Model class for FormHandler using DBIx::Class
SYNOPSIS
Subclass your form from HTML::FormHandler::Model::DBIC:
package MyApp:Form::User;
use Moose;
extends 'HTML::FormHandler::Model::DBIC';There are two ways to get a valid DBIC model: specify the 'item_id' (primary key), 'item_class' (source_name), and 'schema', or pass in an 'item'.
You can specify the "item_class" in your form:
# Associate this form with a DBIx::Class result class
has '+item_class' => ( default => 'User' ); # 'User' is the DBIC source_name The 'item_id' and 'schema' must be passed in when the form is used in your controller. ( also see Catalyst::Controller::Role::HTML::FormHandler )
If an 'item' is passed in, the 'item_id', 'item_class', and 'schema' will be derived from the 'item'.
To use FormHandler to create new database records, pass in undef for the item_id, and supply an 'item_class' and 'schema', or pass in an empty row (using the resultset 'new_result' method).
The field names in the profile of your form should match column, relationship, or accessor names in your DBIx::Class result source.
DESCRIPTION
This DBIC model for HTML::FormHandler 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 relationship), and will save the selected values (one value for 'Select', multiple values in a mapping table for a 'Multiple' field).
This model supports using DBIx::Class result_source accessors just as if they were standard columns. This allows you to provide alternative getters and setters for use in your form.
Since the forms that use this model are subclasses of it, you can subclass any of the subroutines to provide custom functionality.
More information is available from:
Catalyst::Controller::HTML::FormHandler
Catalyst::Controller::Role::HTML::FormHandler
METHODS
schema
Stores the schema that is either passed in, created from the model name in the controller, or created from the Catalyst context and the item_class in the plugin.
update_from_form
my $validated = $form->update_from_form( item => $row );
or
my $validated = $form->update_form_form( item_id => undef, schema => $schema );This is not the same as the subroutine called with $c->update_from_form--the Catalyst controller/role routine that calls this one. This method updates or creates the object from values in the form.
All fields that refer to columns and have been changed will be updated. Field names that are a single relationship will be updated. Any field names that are related to the class by "has_many" and have the 'multiple' flag set 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 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.
model_validate
The place to put validation that requires database-specific lookups. Subclass this method in your form. Validation of unique fields is called from this method.
update_model
Updates the database. 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 column, relationship, select, multiple, or 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_column". 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.
build_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 item_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 );If a database row for the item_id is not found, item_id will be set to undef.
set_item
Trigger that executes when 'item' is set. Sets 'item_id', 'item_class', and 'schema' from the 'item'.
build_schema
For initializing the DBIx::Class schema. User may override. Default is to die if a schema does not exist.
Pass schema in on new:
$my_form_class->new(item_id => $id, schema => $schema)Or pass in a row (result) object ('item'), and the schema will be set from the result object.
source
Returns a DBIx::Class::ResultSource object for this Result Class.
resultset
This method returns a resultset from the "item_class" specified in the form, or from the foreign class that is retrieved from a relationship.
SUPPORT
The author can be contacted through the Catalyst or DBIx::Class mailing lists or IRC channels (gshank).
SEE ALSO
HTML::FormHandler HTML::FormHandler::Field HTML::FormHandler::Model::CDBI Catalyst::Controller:HTML::FormHandler Rose::Object
AUTHOR
Gerda Shank, gshank@cpan.org
Based on the original source code of Form::Processor::Model by Bill Moseley
COPYRIGHT
This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.