C3, inheritence changes and adding skeleton DFV model

[maypole.git] / lib / Maypole / Manual / Inheritance.pod

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