Incorporated comments from Kieren into Manual/Terminology.pod

git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@421 48953598-375a-da11-a14b-00016c27c3ee

diff --git a/lib/Maypole/Manual/Terminology.pod b/lib/Maypole/Manual/Terminology.pod
index 3e9a53ac0f64b0066d342f684298d1b9cc38f1c8..0ef3581fff9e9077fb5287d1c97da8aad34ff0d5 100644 (file)
--- a/lib/Maypole/Manual/Terminology.pod
+++ b/lib/Maypole/Manual/Terminology.pod
@@ -61,7 +61,11 @@ avoid using this term altogether.
 \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
@@ -82,18 +86,21 @@ class.
 \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 called a 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
@@ -111,6 +118,11 @@ Here's one opinion:
 \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
@@ -122,7 +134,7 @@ practice it works well.
 \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
@@ -142,32 +154,32 @@ The distinction is probably unimportant when using Maypole in 'default' mode -
 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
+However, in many applications, a more complex domain model is required, or may\r
+already exist (see L<Maypole::Manual::Inheritance>). In this case, the Maypole\r
+model is more clearly seen as a layer that sits on top of the custom domain\r
+model, and controls access to it from the web UI. In this kind of situation, it\r
+seems more helpful to think of the Maypole model as part of the controller (or\r
+as a Presentation Model - see below).\r
+\r
+This conceptualisation helps developers maintain a separation between the\r
+Maypole model classes, and their own domain model. Without this distinction,\r
+developers may add domain-specific code to the Maypole model classes. To a\r
+certain extent, this is fine. But if you find yourself adding lots of\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
+there to directly support Exported methods, consider whether you could separate\r
+out the domain model into a separate hierarchy of classes that you import into\r
+the Maypole model. See L<Maypole::Manual::Inheritance>.\r
+\r
+Otherwise, there will be two uncoupled code bases, living in the same files,\r
+interacting through a relatively small number of methods. These methods should\r
+in fact become the public API of the domain model, which should be moved to a\r
+separate class hierarchy.\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. 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