/lib/HTML/FormHandler/Model.pm

  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;