\r
+\r
|\r
- +-- --+\r
- |\r
+ +- -+\r
|\r
+\r
\r
\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 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
-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
\r
- THE DRIVER\r
+ THE DRIVER\r
+------- init() is a factory method,\r
1 Maypole | it sets up the view\r
Maypole::Config <----- config(); | classes\r
model(); init(); *-------+ THE VIEW\r
- | view_object(); -------+ \r
+ | view_object(); -------+\r
| +--------------* setup(); | Maypole::View::Base\r
| | + | +\r
| | | | 1 |\r
- | | Apache::MVC *-----+ +-----> Maypole::View::TT\r
- | | + | (or another view class)\r
- | | | |\r
- | | PLUGINS |\r
- | | + |\r
- | | | +----- or CGI::Maypole\r
- | | BeerDB or MasonX:::Maypole\r
+ | | PLUGINS Apache::MVC *-----+ +-----> Maypole::View::TT\r
+ | | + + | (or another view class)\r
+ | | | | |\r
+ | | +-----+-----+ |\r
+ | | | |\r
+ | | BeerDB +----- or CGI::Maypole\r
+ | | or MasonX:::Maypole\r
| |\r
| setup() is a factory method,\r
| it sets up the model\r
| classes\r
|\r
- | THE MODEL\r
+ | THE MODEL\r
|\r
- | Maypole::Model::Base Class::DBI\r
- | + +\r
- | | | \r
- +-------> Maypole::Model::CDBI \r
- + \r
- | \r
+ | Maypole::Model::Base Class::DBI\r
+ | + + +\r
+ | | | |\r
+ +-------> Maypole::Model::CDBI Class::DBI::<db_driver>\r
+ + +\r
+ | |\r
+------------+--------+-------+---------+\r
| | | | |\r
BeerDB::Pub | BeerDB::Beer | BeerDB::Brewery\r
pub(); BeerDB::Style\r
beer(); beers();\r
\r
+=head2 Ouch, that's a lot of inheritence!\r
\r
-=head2 What about Maypole::Application - loading plugins\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
-The main job of L<Maypole::Application> is to insert the plugins into the \r
-hierarchy. It ensures that L<BeerDB> inherits from the first plugin, which \r
-inherits from the next, etc., until the last plugin inherits from the frontend. \r
+=head2 What about Maypole::Application - loading plugins\r
\r
-It is also the responsibility of L<Maypole::Application> to decide which \r
-frontend to use. \r
+The main job of L<Maypole::Application> is to insert the plugins into the\r
+hierarchy. It is also the responsibility of L<Maypole::Application> to decide\r
+which frontend to use. It builds the list of plugins, then pushes them onto the\r
+driver's C<@ISA>, then pushes the frontend onto the end of the driver's C<@ISA>.\r
+So method lookup first searches all the plugins, before searching the frontend\r
+and finally L<Maypole> itself.\r
\r
From Maypole 2.11, L<Maypole::Application> makes no appearance in the\r
inheritance structure of a Maypole application. (In prior versions,\r
L<Maypole::Application> would make itself inherit the plugins, and then insert\r
itself in the hierarchy, but this was unnecessary).\r
\r
-The order of inheritance is the same as the order in which plugins are supplied \r
-in the C<use Maypole::Application> statement. \r
-\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
-First, C<Maypole::setup> calls C<setup_database> on the Maypole model class, in\r
-this case L<Maypole::Model::CDBI>. C<setup_database> then uses\r
+First, C<Maypole::setup_model> calls C<setup_database> on the Maypole model\r
+class, in this case L<Maypole::Model::CDBI>. C<setup_database> then uses\r
L<Class::DBI::Loader> to autogenerate individual L<Class::DBI> classes for each\r
of the tables in the database (C<BeerDB::Beer>, C<BeerDB::Pub> etc).\r
+L<Class::DBI::Loader> identifies the appropriate L<Class::DBI> subclass and\r
+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
use base 'OfflineBeer::Beer';\r
1;\r
\r
-This package will be loaded automatically during C<setup()>, and\r
-C<BeerDB2::Maypole::Model> is B<unshifted> onto it's C<@ISA>. \r
+From Maypole 2.11, this package will be loaded automatically during C<setup()>,\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
|\r
Maypole::Model::Base |\r
+ |\r
- | +----------------------+-----------------+\r
- | | |\r
- | | |\r
- Maypole::Model::CDBI | OFFLINE\r
- + | MODEL\r
- | |\r
- BeerDB2::Maypole::Model OfflineBeer\r
- + +\r
- | |\r
+ | +-----------------+----+-----------------+\r
+ | | | |\r
+ | | | |\r
+ Maypole::Model::CDBI | | OFFLINE\r
+ + | | MODEL\r
+ | | |\r
+ BeerDB2::Maypole::Model Class::DBI::<db_driver> OfflineBeer\r
+ + + +\r
+ | | |\r
+ +-----------------------------+ |\r
| |\r
+--- BeerDB2::Pub --------+ OfflineBeer::Pub --------+\r
| beers(); |\r
\r
=head3 Features\r
\r
-Non-Maypole applications using the Offline model are completely isolated from\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
-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
+2. Methods defined in the Maypole table classes, override methods defined in the\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
C<OfflineBeer::Beer> and finally C<OfflineBeer>.\r
\r
-Methods defined in the Maypole model base class (C<BeerDB2::Maypole::Model>),\r
+B<CAVEAT> - if your Offline model overrides L<Class::DBI> methods, these methods\r
+will B<not> be overridden when called from the Maypole application, because the\r
+Maypole model provides an alternative path to L<Class::DBI> which is searched\r
+first. The solution is to place such methods in a separate package, e.g.\r
+C<OfflineBeer::CDBI>. Place this B<first> in the C<@ISA> of both\r
+C<BeerDB2::Maypole::Model> and C<OfflineBeer>. Note that C<OfflineBeer::CDBI>\r
+does not itself need to inherit from L<Class::DBI>.\r
+\r
+3. Methods defined in the Maypole model base class (C<BeerDB2::Maypole::Model>),\r
override methods in the individual Offline table classes, and in the Offline\r
model base class (C<Offline>). \r
\r
-Relationships defined in the Offline classes are inherited by the Maypole model.\r
+4. Relationships defined in the Offline classes are inherited by the Maypole\r
+model.\r
\r
-The Maypole model has full access to the underlying Offline model. \r
+5. The Maypole model has full access to the underlying Offline model. \r
\r
=head3 Theory \r
\r
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
+David Baird, C<< <cpan@riverside-cms.co.uk> >>\r
+\r
+=head1 COPYRIGHT & LICENSE\r
+\r
+Copyright 2005 David Baird, All Rights Reserved.\r
+\r
+This text is free documentation; you can redistribute it and/or modify it\r
+under the same terms as the Perl documentation itself.\r
+\r
+=cut\r
+\r
projects / maypole.git / blobdiff