common enough), the driver class will directly inherit from one of Maypole's \r
frontend classes. \r
\r
+=item controller\r
+\r
+Occasionally this term is used in place of C<driver>.\r
+\r
+See the entry below (MVC) for the main usage of the term C<controller> within \r
+Maypole. \r
+\r
=item application\r
\r
-Sometimes this is used to refer to the driver, but this term is best reserved \r
-to refer to the complete application, i.e. driver, plugins, templates, model, \r
-the whole shebang.\r
+Sometimes this is used to refer to the driver, or the driver plus configuration\r
+data, but this term is best reserved to refer to the complete application, i.e.\r
+driver, plugins, templates, model, config, the whole shebang.\r
\r
=item frontend\r
\r
An adapter class that allows Maypole to work in a number of different server \r
environments. The currently available frontends are:\r
\r
- Frontend Distribution Environment\r
- ==============================================\r
- CGI::Maypole Maypole CGI\r
- Apache::MVC Maypole Apache/mod_perl and Apache2/mod_perl2\r
- MasonX::Maypole MasonX::Maypole Apache/mod_perl with Mason\r
+ Frontend Distribution Environment\r
+ ==============================================\r
+ CGI::Maypole Maypole CGI\r
+ Apache::MVC Maypole Apache/mod_perl or Apache2/mod_perl2\r
+ MasonX::Maypole MasonX::Maypole Apache/mod_perl with Mason\r
\r
The driver class inherits from the appropriate frontend, which inherits from \r
L<Maypole>.\r
\r
=item request\r
\r
-The Maypole request object. \r
+The Maypole request object. This contains all data sent in the request\r
+(including headers, cookies, CGI parameters), and accumulates data to be sent in\r
+the response (headers and content). It also provides access to the configuration\r
+object, and stores the information parsed out of the URL (action, table, args\r
+etc.). Plugins often add methods and further data members to the request object. \r
\r
=item workflow\r
\r
\r
An Exported method.\r
\r
-Note: not the action attribute of a form, although the form's action URI will \r
-generally include a Maypole action component.\r
+Note: this is not the action attribute of a form, although the form's action URI\r
+will generally include a Maypole action component. For instance, a form might\r
+submit to the following URL: C<[% $base %]/beer/drink/5>. The form action is the\r
+URL, whereas the Maypole action is the C<drink> method on the C<BeerDB::Beer>\r
+object with an ID of 5.\r
\r
=item command\r
\r
-In some templates, an C<action> is called a C<command>.\r
+In some of the standard factory templates, an C<action> is referred to as a \r
+C<command>.\r
\r
=item template\r
\r
A file used to generate HTML for part or all of a web page. Maypole currently \r
supports Template Toolkit and Mason as templating languages, but others could \r
-be added easily.\r
+be added easily. Of course, a template doesn't have to generate only HTML.\r
+\r
+=back\r
\r
=head2 MVC and Maypole\r
\r
-=item MVC - Model-View-Controller\r
+=head3 MVC - Model-View-Controller\r
\r
A pattern describing separation of concerns in a complex application. The \r
C<model> represents the domain or business logic. The C<view> represents the \r
\r
Here's one opinion:\r
\r
-=over 4\r
+=over 4 \r
+\r
+=item view\r
+\r
+This is represented in Maypole by the view class (L<Maypole::View::TT>, \r
+L<Maypole::View::Mason>, or L<MasonX::Maypole::View>), and by the templates. \r
\r
=item controller\r
\r
An abstract concept in Maypole, i.e. there is no specific controller class. \r
\r
-The main sequence of events that occur during the processing of a request is \r
-controlled by methods in L<Maypole>. Thus, major parts of the controller are in \r
-the same class as the request object. This may seem a bit strange, but in \r
-practice it works well.\r
+The main sequence of events that occur during the processing of a request is\r
+controlled by methods in C<Maypole.pm>. Thus, the controller logic is in the\r
+same class as the request object. This may seem a bit strange, but in practice\r
+it works well.\r
\r
More detailed events within the processing of a request are actually handled by \r
methods in the Maypole 'model'. For instance, switching from one template to \r
-another. \r
+another - the "Template Switcheroo" referred to in L<Maypole::Manual::Cookbook>. \r
+\r
+Be aware that occasionally authors refer to the C<controller> when they are\r
+describing the C<driver>.\r
\r
=item model\r
\r
-In Maypole, the model is the set of classes representing individual tables in \r
-the database. Tables are related to each other in a more or less complex \r
-way. Each table class inherits from a Maypole model class, such as \r
-L<Maypole::Model::CDBI> or L<Maypole::Model::CDBI::Plain>. \r
+In Maypole, the 'model' is the set of classes representing individual tables in\r
+the database. Tables are related to each other in a more or less complex way.\r
+Each table class inherits from a Maypole model class, such as\r
+L<Maypole::Model::CDBI> or L<Maypole::Model::CDBI::Plain>.\r
\r
-In fact, much of the functionality provided by the Maypole model class, may be \r
-better thought of as being controller code. And much of the custom code written \r
-by developers to support specific applications, is in fact controller code. \r
+The functionality provided by the Maypole model class is more accurately\r
+described as a Presentation Model (see below). In complex Maypole applications,\r
+it is good practise to separate the domain model (the 'heart' of the\r
+application) into a separate class hierarchy (see\r
+L<Maypole::Manual::Inheritance>).\r
\r
-The distinction is probably unimportant when using Maypole in 'default' mode - \r
+The distinction is relatively unimportant when using Maypole in 'default' mode - \r
i.e. using L<Maypole::Model::CDBI>, and allowing Maypole to autogenerate the \r
'model' classes straight out of the database. \r
\r
-However, in many applications, a more complex domain model is required, or may \r
-already exist. In this case, the Maypole model is more clearly seen as a layer \r
-that sits on top of the custom domain model, and controls access to it from \r
-the web UI. In this kind of situation, it seems more helpful to think of the \r
-Maypole model as part of the controller. This conceptualisation helps developers \r
-maintain a separation between the Maypole model classes, and their own domain \r
-model. Without this distinction, developers may add domain-specific code \r
-to the Maypole model classes, ending up with two separate code bases \r
-intermingled within one set of files. \r
-\r
-To a certain extent, this is fine. But if you find yourself adding lots on \r
-non-Exported methods to your Maypole model classes, \r
-and these methods are not there to support Exported methods, consider whether \r
-you could separate out the domain model into a separate hierarchy of classes \r
-that you import into the Maypole model. \r
-\r
-The distinction between the Maypole model, the domain model, and the model in \r
-the MVC pattern, is fuzzy and variable. In straightforward Maypole applications, \r
-they're all pretty much the same thing. In more advanced applications, they \r
-begin to diverge. Take care out there. \r
-\r
-=item view\r
-\r
-This is represented in Maypole by the view class (L<Maypole::View::TT>, \r
-L<Maypole::View::Mason>, or L<MasonX::Maypole::View>), and by the templates. \r
-\r
+However, in many applications, a more complex domain model is required, or may\r
+already exist. In this case, the Maypole model is more clearly seen as a layer\r
+that sits on top of the domain model, mediating access to it from the web UI, \r
+via the controller.\r
+\r
+This conceptualisation helps developers maintain a separation between the\r
+Maypole model classes (presentation model), and the domain model. Without this\r
+distinction, developers may add domain-specific code to the Maypole model\r
+classes. To a certain extent, in simple applications, this is fine. But if you\r
+find yourself adding lots of non-Exported methods to your Maypole model classes,\r
+and these methods are not there to directly support Exported methods, consider\r
+whether you could separate out the domain model into a separate hierarchy of\r
+classes - see L<Maypole::Manual::Inheritance>.\r
+\r
+Otherwise, the 'model' classes may develop into two quite uncoupled code bases,\r
+but which co-exist in the same files. They will interact through a relatively\r
+small number of methods. These methods should in fact become the public API of\r
+the domain model, which should be moved to a separate class hierarchy. At some\r
+point, the convenience of dropping new methods into the 'shared' classes will be\r
+outweighed by the heuristic advantage of separating different layers into\r
+separate class hierarchies.\r
\r
=back\r
\r
+=head3 Presentation Model\r
+\r
+This pattern more accurately describes the role of the Maypole model.\r
+Martin Fowler describes I<Presentation Model> in L<Separting presentation logic\r
+from the View|http://www.martinfowler.com/eaaDev/OrganizingPresentations.html>\r
+and L<Presentation\r
+Model|http://www.martinfowler.com/eaaDev/PresentationModel.html>.\r
+\r
+The user sends an event (e.g. an HTTP request) to the Controller. The Controller\r
+translates the request into a method call on the Presentation Model. The\r
+Presentation Model interacts with the underlying Domain Model, and stores the\r
+results in a bunch of variables, which I<represent the new state of the View>\r
+(that's why it's a Presentation Model, not a Domain Model). The View then\r
+queries the Presentation Model to retrieve these new values. In Maypole, this is\r
+the role of the C<vars()> method on L<Maypole::View::Base>, which transmits the\r
+new values to the templates.\r
+\r
=head1 AUTHOR\r
\r
David Baird, C<< <cpan@riverside-cms.co.uk> >>\r
projects / maypole.git / blobdiff