X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=lib%2FMaypole%2FManual%2FInheritance.pod;h=950283deb960c2610032c34d5e2112425af1bd98;hb=dd425b2cb6384f804cc1eea9e45660ed6baeb2f1;hp=6c6c6b77eba53e34624cf88766ec64bb52017412;hpb=ea4ae8a93a09e21354465c485471e5f10582b784;p=maypole.git

diff --git a/lib/Maypole/Manual/Inheritance.pod b/lib/Maypole/Manual/Inheritance.pod
index 6c6c6b7..950283d 100644
--- a/lib/Maypole/Manual/Inheritance.pod
+++ b/lib/Maypole/Manual/Inheritance.pod
@@ -30,11 +30,11 @@ application.
 
 =back
 
-=head1 A standard Maypole application
+=head1 Structure of a standard Maypole application
 
-A minimal Maypole application (such as the Beer database) consists of a 
-custom driver class (BeerDB.pm), a set of auto-generated model classes, and a 
-view class: 
+A minimal Maypole application (such as the Beer database example from the
+L<Maypole> synopsis) consists of a custom driver (or controller) class (BeerDB.pm),
+a set of auto-generated model classes, and a view class:
 
 
            THE DRIVER
@@ -76,6 +76,11 @@ view class:
           pub();                      BeerDB::Style
           beer();                     beers();
 
+=head2 Ouch, that's a lot of inheritence!
+
+Yes, that's a lot of inheritence, at some point in the future - probably Maypole 3.x we
+will move to Class::C3
+
 =head2 What about Maypole::Application - loading plugins
 
 The main job of L<Maypole::Application> is to insert the plugins into the
@@ -92,9 +97,10 @@ itself in the hierarchy, but this was unnecessary).
 
 =head2 Who builds the model?
 
-First, remember we are talking about the standard, unmodified Maypole here. 
-It is possible, and common, to override some or all of this stage and build a 
-customised model.
+First, remember we are talking about the standard, unmodified Maypole here. It
+is possible, and common, to override some or all of this stage and build a
+customised model. See below - An advanced Maypole application - for one
+approach. Also, see L<Maypole's|Maypole> C<setup_model()> method. 
 
 The standard model is built in 3 stages. 
 
@@ -106,14 +112,16 @@ L<Class::DBI::Loader> identifies the appropriate L<Class::DBI> subclass and
 inserts it into each of these table classes' C<@ISA> ( C<<
 Class::DBI::<db_driver> >> in the diagrams)..
 
-Next, C<Maypole::setup> B<unshifts> L<Maypole::Model::CDBI> onto the C<@ISA> 
+Next, C<Maypole::setup> B<pushes> L<Maypole::Model::CDBI> onto the C<@ISA> 
 array of each of these classes. 
 
 Finally, the relationships among these tables are set up. Either do this
-manually, perhaps with the help of L<Class::DBI::Relationship>, or use
-L<Maypole::Plugin::Relationship>. In the latter case, you need to set up the
-relationships configuration before calling C<setup()>.
-
+manually, using the standard L<Class::DBI> syntax for configuring table
+relationships, or try L<Class::DBI::Relationship> (which you can use via
+L<Maypole::Plugin::Relationship>). If you use the plugin, you need to set up the
+relationships configuration before calling C<setup()>. Be aware that some people
+like the convenience of L<Class::DBI::Relationship>, others dislike the
+abstraction. YMMV. 
 
 =head1 An advanced Maypole application
 
@@ -181,7 +189,7 @@ C<BeerDB2::Beer>, you would write:
     1;
     
 From Maypole 2.11, this package will be loaded automatically during C<setup()>,
-and C<BeerDB2::Maypole::Model> is B<unshifted> onto it's C<@ISA>.
+and C<BeerDB2::Maypole::Model> is B<pushed> onto it's C<@ISA>.
 
 Configure relationships either in the individual C<OfflineBeer::*> classes, or
 else all together in C<OfflineBeer> itself i.e. not in the Maypole model. This 
@@ -231,8 +239,8 @@ The resulting model looks like this:
 the Maypole application, and need not know it exists at all.
 
 2. Methods defined in the Maypole table classes, override methods defined in the
-Offline table classes, because C<BeerDB2::Maypole::Model> was unshifted onto the
-beginning of each Maypole table class's C<@ISA>. Perl's depth first,
+Offline table classes, because C<BeerDB2::Maypole::Model> was pushed onto the
+end of each Maypole table class's C<@ISA>. Perl's depth first,
 left-to-right method lookup from e.g. C<BeerDB2::Beer> starts in
 C<BeerDB2::Beer>, then C<BeerDB2::Maypole::Model>, C<Maypole::Model::CDBI>,
 C<Maypole::Model::Base>, and C<Class::DBI>, before moving on to
@@ -270,6 +278,20 @@ calls on the underlying model.
 Whatever label you prefer to use, this approach provides for clear separation of
 concerns between the underlying model and the web/user interface, and that's
 what it's all about.
+
+=head1 Advanced applications - building the model by hand ** TODO
+
+- using Maypole::Model::CDBI::Plain or Maypole::FormBuilder::Model::Plain
+- setup_model() and load_model_subclass()
+- cutting out all those separate paths to CDBI - they're confusing 
+
+
+=head1 Method inheritance ** TODO
+
+More description of Perl's left-to-right, depth-first method lookup, and where
+it's particularly important in Maypole.
+
+
           
 =head1 AUTHOR