From: Marcus Ramberg <mramberg@cpan.org>
Date: Mon, 11 Oct 2004 19:27:20 +0000 (+0000)
Subject: Shitload of doc fixes.
X-Git-Tag: 2.10~141
X-Git-Url: https://git.decadent.org.uk/gitweb/?a=commitdiff_plain;h=ef3da5818c452a331e863d30efc41f5b65d0f624;p=maypole.git

Shitload of doc fixes.
Added list_columns for use in list template.


git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@221 48953598-375a-da11-a14b-00016c27c3ee
---

diff --git a/lib/Maypole/Config.pm b/lib/Maypole/Config.pm
index e0bf6ee..54f2c1e 100644
--- a/lib/Maypole/Config.pm
+++ b/lib/Maypole/Config.pm
@@ -9,7 +9,7 @@ use warnings;
 __PACKAGE__->mk_accessors(
     qw( view uri_base template_root model loader display_tables ok_tables
       rows_per_page dsn user pass opts application_name document_encoding
-      content_type)
+      content_type models)
 );
 
 # Should only be modified by model.
diff --git a/lib/Maypole/Constants.pm b/lib/Maypole/Constants.pm
index a758584..b79704f 100644
--- a/lib/Maypole/Constants.pm
+++ b/lib/Maypole/Constants.pm
@@ -4,4 +4,30 @@ use constant OK       => 0;
 use constant DECLINED => -1;
 use constant ERROR    => -1;
 our @EXPORT = qw(OK DECLINED ERROR);
+
+=head1 NAME
+
+Maypole::Constants - Maypole predefined constants
+
+=head1 DESCRIPTION
+
+This class defines constants for use with Maypole
+
+=head1 SEE ALSO
+
+L<Maypole>
+
+=head1 MAINTAINER
+
+Sebastian Riedel, c<sri@oook.de>
+
+=head1 AUTHOR
+
+Simon Cozens, C<simon@cpan.org>
+
+=head1 LICENSE
+
+You may distribute this code under the same terms as Perl itself.
+
+=cut
 1;
diff --git a/lib/Maypole/Manual/StandardTemplates.pod b/lib/Maypole/Manual/StandardTemplates.pod
index e5eb9f0..3c8bc69 100644
--- a/lib/Maypole/Manual/StandardTemplates.pod
+++ b/lib/Maypole/Manual/StandardTemplates.pod
@@ -252,7 +252,7 @@ macros as we come across them.
 
 =head3 F<view> 
 
-=template view
+template view
 
 =head3 F<edit>
 
diff --git a/lib/Maypole/Model/Base.pm b/lib/Maypole/Model/Base.pm
index b6ef5f4..ea1632a 100644
--- a/lib/Maypole/Model/Base.pm
+++ b/lib/Maypole/Model/Base.pm
@@ -9,12 +9,6 @@ sub MODIFY_CODE_ATTRIBUTES { $remember{ $_[1] } = $_[2]; () }
 
 sub FETCH_CODE_ATTRIBUTES { $remember{ $_[1] } }
 
-sub view : Exported {
-}
-
-sub edit : Exported {
-}
-
 sub process {
     my ( $class, $r ) = @_;
     my $method = $r->action;
@@ -30,6 +24,10 @@ sub process {
     $class->$method( $r, $obj, @{ $r->{args} } );
 }
 
+sub list_columns {
+    shift->display_columns;
+}
+
 sub display_columns {
     sort shift->columns;
 }
@@ -40,20 +38,16 @@ Maypole::Model::Base - Base class for model classes
 
 =head1 DESCRIPTION
 
-Anyone subclassing this for a different database abstraction mechanism
-needs to provide the following methods:
+This is the base class for Maypole data models. This is an abstract class
+meant to define the interface, and can't be used directly.
 
-=head2 do_edit
+=head2 process
 
-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
-be created with those parameters, and put back into C<$r-E<gt>objects>.
-The template should be changed to C<view>, or C<edit> if there were any
-errors. A hash of errors will be passed to the template.
+This is the engine of this module. It populates all the relevant variables
+and calls the requested action.
 
-=cut
-
-sub do_edit { die "This is an abstract method" }
+Anyone subclassing this for a different database abstraction mechanism
+needs to provide the following methods:
 
 =head2 setup_database
 
@@ -83,43 +77,67 @@ This turns an ID into an object of the appropriate class.
 This is called on an model class representing a table and allows the
 master model class to do any set-up required. 
 
-=head2 related
-
-This can go either in the master model class or in the individual
-classes, and returns a list of has-many accessors. A brewery has many
-beers, so C<BeerDB::Brewery> needs to return C<beers>.
-
 =head2 columns
 
 This is a list of all the columns in a table. You may also override
-C<display_columns>, which is the list of columns you want to view, in
-the right order.
+see also C<display_columns>
 
 =head2 table
 
 This is the name of the table.
 
+=cut 
+
+sub class_of       { die "This is an abstract method" }
+sub setup_database { die "This is an abstract method" }
+
 =head2 Commands
 
 =over
 
+=item 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
+be created with those parameters, and put back into C<$r-E<gt>objects>.
+The template should be changed to C<view>, or C<edit> if there were any
+errors. A hash of errors will be passed to the template.
+
+=cut
+
+sub do_edit { die "This is an abstract method" }
+
+
 =item list
 
 The C<list> method should fill C<< $r-> objects >> with all of the
 objects in the class. You may want to page this using C<Data::Page> or
 similar.
 
+=item edit
+
+Empty Action
+
+=item view
+
+Empty Action.
+
+
 =back
 
 =cut
 
-sub class_of       { die "This is an abstract method" }
-sub setup_database { die "This is an abstract method" }
 
 sub list : Exported {
     die "This is an abstract method";
 }
 
+sub view : Exported {
+}
+
+sub edit : Exported {
+}
+
 =pod
 
 Also, see the exported commands in C<Maypole::Model::CDBI>.
@@ -129,6 +147,16 @@ Also, see the exported commands in C<Maypole::Model::CDBI>.
 Additionally, individual derived model classes may want to override the
 following methods:
 
+=head2 display_columns
+
+Returns a list of columns to display in the model. by default returns
+all columns in alphabetical order. Override this in base classes to
+change ordering, or elect not to show columns.
+
+=head2 list_columns
+
+Same as display_columns, only for listings. Defaults to display_columns
+
 =head2 column_names
 
 Return a hash mapping column names with human-readable equivalents.
@@ -152,6 +180,13 @@ A description of the class to be passed to the template.
 
 sub description { "A poorly defined class" }
 
+=head2 is_public
+
+should return true if a certain action is supported, or false otherwise. 
+Defaults to checking if the sub has the :Exported attribute.
+
+=cut
+
 sub is_public {
     my ( $self, $action ) = @_;
     my $cv = $self->can($action);
@@ -164,4 +199,15 @@ sub is_public {
     return 1;
 }
 
+=head2 related
+
+This can go either in the master model class or in the individual
+classes, and returns a list of has-many accessors. A brewery has many
+beers, so C<BeerDB::Brewery> needs to return C<beers>.
+
+=cut
+
+sub related {
+}
+
 1;
diff --git a/lib/Maypole/Model/CDBI.pm b/lib/Maypole/Model/CDBI.pm
index 171c916..5432561 100644
--- a/lib/Maypole/Model/CDBI.pm
+++ b/lib/Maypole/Model/CDBI.pm
@@ -22,6 +22,43 @@ work of fetching rows and representing them as objects. It is a good
 model to copy if you're replacing it with other database abstraction
 modules.
 
+It implements a base set of methods required for a Maypole Data Model.
+See L<Maypole::Model::Base> for these:
+
+=over 4
+
+=item adopt
+
+=item class_of
+
+=item do_edit
+
+=item list
+
+=item related
+
+=item setup_database
+
+=back 
+
+=head1 Additional Commands
+
+=over 
+
+=item delete
+
+Surprisingly, this command causes a database record to be forever lost.
+
+=item search
+
+=head1 Helper Methods
+
+=item order
+
+=item stringify_column
+
+=item do_pager
+
 =cut
 
 sub related {
@@ -29,6 +66,16 @@ sub related {
     return keys %{ $self->meta_info('has_many') || {} };
 }
 
+#sub related_class {
+#    my ( $self, $r, $accessor ) = @_;
+#    my $related=$self->related->{$accessor};
+#    if ( my $mapping=$related->{args}->{mapping} ) {
+#	return	$related->{foreign_class}->meta_info('has_a')->{$$mapping[0]}->{foreign_class};
+#    } else { 
+#	return $related->{foreign_class};
+#    }
+#}
+
 sub do_edit : Exported {
     my ( $self, $r ) = @_;
     my $h        = CGI::Untaint->new( %{ $r->{params} } );
diff --git a/lib/Maypole/Model/CDBI/Plain.pm b/lib/Maypole/Model/CDBI/Plain.pm
index 2c2d869..6c2709c 100644
--- a/lib/Maypole/Model/CDBI/Plain.pm
+++ b/lib/Maypole/Model/CDBI/Plain.pm
@@ -36,5 +36,17 @@ C<Class::DBI> classes; simply call C<setup> with a list reference
 of the classes you're going to use, and Maypole will work out the
 tables and set up the inheritance relationships as normal.
 
+=head1 METHODS
+
+=over 4
+
+=item setup_database
+
+=item  class_of
+
+=back
+
+See L<Maypole::Model::Base>
+
 =cut
 
diff --git a/lib/Maypole/View/Base.pm b/lib/Maypole/View/Base.pm
index b577364..e7bf299 100644
--- a/lib/Maypole/View/Base.pm
+++ b/lib/Maypole/View/Base.pm
@@ -38,6 +38,7 @@ sub vars {
             name              => $class,
             table             => $class->table,
             columns           => [ $class->display_columns ],
+            list_columns      => [ $class->list_columns ],
             colnames          => { $class->column_names },
             related_accessors => [ $class->related($r) ],
             moniker           => $class->moniker,
diff --git a/lib/Maypole/View/TT.pm b/lib/Maypole/View/TT.pm
index 9a15dfa..21e2485 100644
--- a/lib/Maypole/View/TT.pm
+++ b/lib/Maypole/View/TT.pm
@@ -35,6 +35,16 @@ Please see the Maypole manual, and in particular, the C<View> chapter,
 for the template variables available and for a refresher on how template
 components are resolved.
 
+=over 4
+
+=item template
+
+
+Processes the template and sets the output. See L<Maypole::View::Base>
+
+=back
+
+
 =head1 AUTHOR
 
 Simon Cozens