some documentation improvements, some test fixes

[maypole.git] / lib / Maypole / Model / CDBI.pm

diff --git a/lib/Maypole/Model/CDBI.pm b/lib/Maypole/Model/CDBI.pm
index a5c65f65166c417f1171ee051e97768713ee188e..5013d4ff54063f9d07f4617f5336f0f3d157cd89 100644 (file)
--- a/lib/Maypole/Model/CDBI.pm
+++ b/lib/Maypole/Model/CDBI.pm
@@ -16,6 +16,11 @@ It implements a base set of methods required for a Maypole Data Model.
 
 It inherits accessor and helper methods from L<Maypole::Model::Base>.
 
+When specified as the application model, it will use Class::DBI::Loader
+to generate the model classes from the provided database. If you do not
+wish to use this functionality, use L<Maypole::Model::CDBI::Plain> which
+will instead use Class::DBI classes provided.
+
 =cut
 
 use base qw(Maypole::Model::Base Class::DBI);
@@ -38,7 +43,7 @@ use attributes ();
 
 Action methods are methods that are accessed through web (or other public) interface.
 
-=item do_edit
+=head2 do_edit
 
 If there is an object in C<$r-E<gt>objects>, then it should be edited
 with the parameters in C<$r-E<gt>params>; otherwise, a new object should
@@ -371,17 +376,36 @@ sub related_class {
      }
  }
 
+=head2 related_meta
+
+  $class->related_meta($col);
+
+Given a column  associated with a relationship it will return the relatation
+ship type and the meta info for the relationship on the column.
+
+=cut
+
+sub related_meta {
+    my ($self,$r, $accssr) = @_;
+    $self->_croak("You forgot to put the place holder for 'r' or forgot the accssr parameter") unless $accssr;
+    my $class_meta = $self->meta_info;
+    if (my ($rel_type) = grep { defined $class_meta->{$_}->{$accssr} }
+        keys %$class_meta)
+    { return  $rel_type, $class_meta->{$rel_type}->{$accssr} };
+}
+
+
 =head2 isa_class
 
-Returns class of a column inherited by is_a, assumes something can be more than one thing (have * is_a rels)
+Returns class of a column inherited by is_a.
 
 =cut
 
+# Maybe put this in IsA?
 sub isa_class {
   my ($class, $col) = @_;
   $class->_croak( "Need a column for isa_class." ) unless $col;
   my $isaclass;
-  # class col is first found in is returned 
   my $isa = $class->meta_info("is_a") || {}; 
   foreach ( keys %$isa ) {
     $isaclass = $isa->{$_}->foreign_class; 
@@ -395,7 +419,8 @@ sub isa_class {
 Returns hash ref of classes for accessors.
 
 This is an attempt at a more efficient method than calling "related_class()"
-a bunch of times when you need it for many relations. 
+a bunch of times when you need it for many relations.
+It may be good to call at startup and store in a global config. 
 
 =cut
 
@@ -421,6 +446,9 @@ sub accessor_classes {
 
 =head2 stringify_column
 
+   Returns the name of the column to use when stringifying
+   and object.
+
 =cut
 
 sub stringify_column {
@@ -435,6 +463,13 @@ sub stringify_column {
 
 =head2 do_pager
 
+   Sets the pager template argument ($r->{template_args}{pager})
+   to a Class::DBI::Pager object based on the rows_per_page
+   value set in the configuration of the application.
+
+   This pager is used via the pager macro in TT Templates, and
+   is also accessible via Mason.
+
 =cut
 
 sub do_pager {
@@ -449,6 +484,16 @@ sub do_pager {
 
 =head2 order
 
+    Returns the SQL order syntax based on the order parameter passed
+    to the request, and the valid columns.. i.e. 'title ASC' or 'date_created DESC'.
+
+    $sql .= $self->order($r);
+
+    If the order column is not a column of this table,
+    or an order argument is not passed, then the return value is undefined.
+
+    Note: the returned value does not start with a space.
+
 =cut
 
 sub order {
@@ -461,8 +506,27 @@ sub order {
     return $order;
 }
 
+=head2 setup
+
+  This method is inherited from Maypole::Model::Base and calls setup_database,
+  which uses Class::DBI::Loader to create and load Class::DBI classes from
+  the given database schema.
+
+=cut
+
 =head2 setup_database
 
+The $opts argument is a hashref of options.  The "options" key is a hashref of
+Database connection options . Other keys may be various Loader arguments or
+flags.  It has this form:
+ {
+   # DB connection options
+   options { AutoCommit => 1 , ... },
+   # Loader args
+   relationships => 1,
+   ...
+ }
+
 =cut
 
 sub setup_database {