/lib/HTML/FormHandler/Model.pm
Perl | 168 lines | 147 code | 20 blank | 1 comment | 8 complexity | 26f9ab2543b45c9826ddc68d781ee7ec MD5 | raw file
1package HTML::FormHandler::Model; 2# ABSTRACT: default model base class 3 4use Moose::Role; 5use Carp; 6 7=head1 SYNOPSIS 8 9This class defines the base attributes for FormHandler model 10classes. It is not used directly. 11 12=head1 DESCRIPTION 13 14This is an empty base class that defines methods called by 15HTML::FormHandler to support interfacing forms with a data store 16such as a database. 17 18This module provides instructions on methods to override to create 19a HTML::FormHandler::Model class to work with a specific object relational 20mapping (ORM) tool. 21 22=head1 METHODS 23 24=head2 item, build_item 25 26The "item" is initialized with "build_item" the first time $form->item is called. 27"item" must be defined in the model class to fetch the object based on the item id. 28It should return the item's object. Column values are fetched and updated 29by calling methods on the returned object. 30 31For example, with Class::DBI you might return: 32 33 return $self->item_class->retrieve( $self->item_id ); 34 35=cut 36 37has 'item' => ( 38 is => 'rw', 39 lazy => 1, 40 builder => 'build_item', 41 clearer => 'clear_item', 42 trigger => sub { shift->set_item(@_) } 43); 44sub build_item { return } 45 46sub set_item { 47 my ( $self, $item ) = @_; 48 $self->item_class( ref $item ); 49} 50 51=head2 item_id 52 53The id (primary key) of the item (object) that the form is updating 54or has just created. The model class should have a build_item method that can 55fetch the object from the item_class for this id. 56 57=cut 58 59has 'item_id' => ( 60 is => 'rw', 61 clearer => 'clear_item_id', 62 trigger => sub { shift->set_item_id(@_) } 63); 64 65sub set_item_id { } 66 67=head2 item_class 68 69"item_class" sets and returns a value used by the model class to access 70the ORM class related to a form. 71 72For example: 73 74 has '+item_class' => ( default => 'User' ); 75 76This gives the model class a way to access the data store. 77If this is not a fixed value (as above) then do not define the 78method in your subclass and instead set the value when the form 79is created: 80 81 my $form = MyApp::Form::Users->new( item_class => $class ); 82 83The value can be any scalar (or object) needed by the specific ORM 84to access the data related to the form. 85 86A builder for 'item_class' might be to return the class of the 'item'. 87 88=cut 89 90has 'item_class' => ( 91 isa => 'Str', 92 is => 'rw', 93); 94 95=head2 guess_field_type 96 97Returns the guessed field type. The field name is passed as the first argument. 98This is only required if using "Auto" type of fields in your form classes. 99You could override this in your form class, for example, if you use a field 100naming convention that indicates the field type. 101 102The metadata info about the columns can be used to assign types. 103 104=cut 105 106sub guess_field_type { 107 Carp::confess "Don't know how to determine field type of [$_[1]]"; 108} 109 110=head2 lookup_options 111 112Retrieve possible options for a given select field from the database. 113The default method returns undef. 114 115Returns an array reference of key/value pairs for the column passed in. 116These values are used for the values and labels for field types that 117provide a list of options to select from (e.g. Select, Multiple). 118 119A 'Select' type field (or a field that inherits from 120HTML::FormHandler::Field::Select) can set a number of scalars that control how 121options are looked up: 122 123 label_column() - column that holds the label 124 active_column() - column that indicates if a row is acitve 125 sort_column() - column used for sorting the options 126 127The default for label_column is "name". 128 129=cut 130 131sub lookup_options { } 132 133=head2 validate_model 134 135Validates fields that are dependent on the model. 136This is called via the validation process and the model class 137must at least validate "unique" constraints defined in the form 138class. 139 140Any errors on a field found should be set by calling the field's 141add_error method: 142 143 $field->add_error('Value must be unique in the database'); 144 145The default method does nothing. 146 147=cut 148 149sub validate_model { } 150 151=head2 clear_model 152 153Clear out any dynamic data for persistent object 154 155=cut 156 157sub clear_model { } 158 159=head2 update_model 160 161Update the model with validated fields 162 163=cut 164 165sub update_model { } 166 167use namespace::autoclean; 1681;