]> git.decadent.org.uk Git - maypole.git/blobdiff - lib/Maypole/Manual/Terminology.pod
tested and it seems to work
[maypole.git] / lib / Maypole / Manual / Terminology.pod
index 05b321ef1c88e055bc78f0a949b6ef07b6a3bcbf..adc5dc85b64d017782b9db0d8d78d5d0d4739c0a 100644 (file)
@@ -21,22 +21,29 @@ 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
 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
 =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
 \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
 The driver class inherits from the appropriate frontend, which inherits from \r
 L<Maypole>.\r
@@ -54,7 +61,11 @@ avoid using this term altogether.
 \r
 =item request\r
 \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
 =item workflow\r
 \r
@@ -75,22 +86,28 @@ class.
 \r
 An Exported method.\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
 \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
 \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
 \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
 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,65 +117,87 @@ Opinions vary between how closely Maypole adheres to this pattern.
 \r
 Here's one opinion:\r
 \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
 \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
 \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
 \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
 \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
 \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
 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
 \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
 =head1 AUTHOR\r
 \r
 David Baird, C<< <cpan@riverside-cms.co.uk> >>\r