/lib/HTML/FormHandler/Model.pm

http://github.com/gshank/html-formhandler · Perl · 168 lines · 158 code · 9 blank · 1 comment · 1 complexity · 26f9ab2543b45c9826ddc68d781ee7ec MD5 · raw file

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