Added a description of Presentation Model to Manual/Terminology.pod

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

diff --git a/lib/Maypole/Manual/Terminology.pod b/lib/Maypole/Manual/Terminology.pod
index 05b321ef1c88e055bc78f0a949b6ef07b6a3bcbf..3e9a53ac0f64b0066d342f684298d1b9cc38f1c8 100644 (file)
--- a/lib/Maypole/Manual/Terminology.pod
+++ b/lib/Maypole/Manual/Terminology.pod
@@ -21,11 +21,18 @@ L<Maypole::Application> to set up your app (not recommended for newbies, but
 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
@@ -88,9 +95,11 @@ A file used to generate HTML for part or all of a web page. Maypole currently
 supports Template Toolkit and Mason as templating languages, but others could \r
 be added easily.\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
@@ -100,21 +109,24 @@ Opinions vary between how closely Maypole adheres to this pattern.
 \r
 Here's one opinion:\r
 \r
-=over 4\r
+=over 4 \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
+The main sequence of events that occur during the processing of a request is\r
+controlled by methods in C<Maypole.pm>. Thus, major parts of the controller are\r
+in the same class as the request object. This may seem a bit strange, but in\r
 practice 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
 \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
@@ -140,22 +152,36 @@ model. Without this distinction, developers may add domain-specific code
 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
+To a certain extent, this is fine. But if you find yourself adding lots on\r
+non-Exported methods to your Maypole model classes, and these methods are not\r
+there to support Exported methods, consider whether you could separate out the\r
+domain model into a separate hierarchy of classes that you import into the\r
+Maypole model. See L<Maypole::Manual::Inheritance>.\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
+begin to diverge. See C<Presentation Model>.  \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
+=head3 Presentation Model\r
+\r
+This pattern seems to more accurately describe 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 View sends events (e.g. an HTTP request that triggers an Exported method) to\r
+the Presentation Model. This layer responds by interacting with the underlying\r
+domain model, and stores the results in a bunch of variables, which represent\r
+the new state of the View. The View then queries the Presentation Model to\r
+retrieve these new values. In Maypole, this is the role of the C<vars()> method \r
+on L<Maypole::View::Base>, which transmits the new values to the templates. \r
 \r
 =back\r
 \r