From f4a654d5fee1b79ced98bb6d71a4f3b4bf402ecd Mon Sep 17 00:00:00 2001 From: David Baird Date: Thu, 10 Nov 2005 10:43:55 +0000 Subject: [PATCH] Re-wrote Manual::Termonology to emphasize that Maypole's model is a Presentation Model, and to remove previous confusing stuff about it being a fine-grained part of the controller. git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@426 48953598-375a-da11-a14b-00016c27c3ee --- Changes | 34 ++++++----- lib/Maypole/Manual/Terminology.pod | 93 +++++++++++++++--------------- 2 files changed, 66 insertions(+), 61 deletions(-) diff --git a/Changes b/Changes index 70ab26d..8067f8a 100644 --- a/Changes +++ b/Changes @@ -9,9 +9,11 @@ Deprecated: in $r->params, or anything else, is DEPRECATED and likely to break in future releases. Be good, and use proper method calls. - is_applicable() renamed to is_model_applicable(), and returns boolean - instead of a status code. Old-style is_applicable() will still work, - but issues a warning. +Incompatible API changes: + Maypole: + - is_applicable() renamed to is_model_applicable(), and returns boolean + instead of a status code. Old-style is_applicable() will still work, + but issues a warning. API additions and enhancements: Maypole::Application: @@ -23,12 +25,13 @@ API additions and enhancements: - user() attribute, and get_user() method (no-op) - get_session() now called during handler_guts() before authenticate() - new preprocess_path() method added and called by parse_path(), - parse_path() will leave any properties set by preprocess_path() in - place + parse_path() will leave any properties set by preprocess_path() in + place - start_request_hook() added - - setup() split into setup(), setup_model(), and load_model_subclass() + - setup() split into setup(), setup_model(), and load_model_subclass() - added new path processing methods for ssl and default table/action - - added make_path() and make_uri() + - added make_path() + - added make_uri() Templates: - Improved pager macro/include @@ -37,24 +40,25 @@ Bug fixes: Fix to TT error reporting (bug 13991) Template xhtml validation (bug 13975) Apache2 fix in Apache::MVC (bug 13888) - Fixed inheritance issues in Mp::Application - Mp::App now manipulates the caller's - @ISA directly, and doesn't inject itself into the chain (bugs 12923 & 14120) + Fixed inheritance issues in Mp::Application - Mp::App now manipulates the + caller's @ISA directly, and doesn't inject itself into the chain (bugs + 12923 & 14120) Improved Template error reporting (14133) Maypole::Session::generate_unique_id() now returns the id (bug 14124) Moved ar accessor to Apache::MVC (bug 14014) Refactored core to support further development in 2.11 and onwards - Fixed related_class method (bug 14566) + Fixed related_class() method (bug 14566) Added a cgi() attribute in Maypole::CGI Documentation: Fix to documentation for CGI::Maypole (bug 7263) Simplified Net::Amazon example (bug 14073) - Numerous major and minor updates to docs, plus: - - renamed Maypole::Manual::Request to Maypole::Manual::Cookbook - - added Maypole::Manual::Install, with material removed from + Numerous major and minor updates to docs. + Renamed Maypole::Manual::Request to Maypole::Manual::Cookbook + Added Maypole::Manual::Install, with material removed from Maypole::Manual::About - - added Maypole::Manual::Inheritance - - added Maypole::Manual::Terminology + Added Maypole::Manual::Inheritance + Added Maypole::Manual::Terminology - updated Maypole::Manual::View - updated Maypole::View:TT diff --git a/lib/Maypole/Manual/Terminology.pod b/lib/Maypole/Manual/Terminology.pod index 0ef3581..d7bf7f4 100644 --- a/lib/Maypole/Manual/Terminology.pod +++ b/lib/Maypole/Manual/Terminology.pod @@ -39,11 +39,11 @@ driver, plugins, templates, model, config, the whole shebang. An adapter class that allows Maypole to work in a number of different server environments. The currently available frontends are: - Frontend Distribution Environment - ============================================== - CGI::Maypole Maypole CGI - Apache::MVC Maypole Apache/mod_perl and Apache2/mod_perl2 - MasonX::Maypole MasonX::Maypole Apache/mod_perl with Mason + Frontend Distribution Environment + ============================================== + CGI::Maypole Maypole CGI + Apache::MVC Maypole Apache/mod_perl or Apache2/mod_perl2 + MasonX::Maypole MasonX::Maypole Apache/mod_perl with Mason The driver class inherits from the appropriate frontend, which inherits from L. @@ -94,7 +94,8 @@ object with an ID of 5. =item command -In some of the standard factory templates, an C is called a C. +In some of the standard factory templates, an C is referred to as a +C. =item template @@ -128,9 +129,9 @@ L, or L), and by the templates. An abstract concept in Maypole, i.e. there is no specific controller class. The main sequence of events that occur during the processing of a request is -controlled by methods in C. Thus, major parts of the controller are -in the same class as the request object. This may seem a bit strange, but in -practice it works well. +controlled by methods in C. Thus, the controller logic is in the +same class as the request object. This may seem a bit strange, but in practice +it works well. More detailed events within the processing of a request are actually handled by methods in the Maypole 'model'. For instance, switching from one template to @@ -141,59 +142,59 @@ describing the C. =item model -In Maypole, the model is the set of classes representing individual tables in -the database. Tables are related to each other in a more or less complex -way. Each table class inherits from a Maypole model class, such as -L or L. +In Maypole, the 'model' is the set of classes representing individual tables in +the database. Tables are related to each other in a more or less complex way. +Each table class inherits from a Maypole model class, such as +L or L. -In fact, much of the functionality provided by the Maypole model class, may be -better thought of as being controller code. And much of the custom code written -by developers to support specific applications, is in fact controller code. +The functionality provided by the Maypole model class is more accurately +described as a Presentation Model (see below). In complex Maypole applications, +it is good practise to separate the domain model (the 'heart' of the +application) into a separate class hierarchy (see +L, and allowing Maypole to autogenerate the 'model' classes straight out of the database. However, in many applications, a more complex domain model is required, or may -already exist (see L). In this case, the Maypole -model is more clearly seen as a layer that sits on top of the custom domain -model, and controls access to it from the web UI. In this kind of situation, it -seems more helpful to think of the Maypole model as part of the controller (or -as a Presentation Model - see below). +already exist. In this case, the Maypole model is more clearly seen as a layer +that sits on top of the domain model, mediating access to it from the web UI, +via the controller. This conceptualisation helps developers maintain a separation between the -Maypole model classes, and their own domain model. Without this distinction, -developers may add domain-specific code to the Maypole model classes. To a -certain extent, this is fine. But if you find yourself adding lots of -non-Exported methods to your Maypole model classes, and these methods are not -there to directly support Exported methods, consider whether you could separate -out the domain model into a separate hierarchy of classes that you import into -the Maypole model. See L. - -Otherwise, there will be two uncoupled code bases, living in the same files, -interacting through a relatively small number of methods. These methods should -in fact become the public API of the domain model, which should be moved to a -separate class hierarchy. - -The distinction between the Maypole model, the domain model, and the model in -the MVC pattern, is fuzzy and variable. In straightforward Maypole applications, -they're all pretty much the same thing. In more advanced applications, they -begin to diverge. See C. +Maypole model classes (presentation model), and the domain model. Without this +distinction, developers may add domain-specific code to the Maypole model +classes. To a certain extent, in simple applications, this is fine. But if you +find yourself adding lots of non-Exported methods to your Maypole model classes, +and these methods are not there to directly support Exported methods, consider +whether you could separate out the domain model into a separate hierarchy of +classes - see L. + +Otherwise, the 'model' classes may develop into two quite uncoupled code bases, +but which co-exist in the same files. They will interact through a relatively +small number of methods. These methods should in fact become the public API of +the domain model, which should be moved to a separate class hierarchy. At some +point, the convenience of dropping new methods into the 'shared' classes will be +outweighed by the heuristic advantage of separating different layers into +separate class hierarchies. =head3 Presentation Model -This pattern seems to more accurately describe the role of the Maypole model. +This pattern more accurately describes the role of the Maypole model. Martin Fowler describes I in L and L. -The View sends events (e.g. an HTTP request that triggers an Exported method) to -the Presentation Model. This layer responds by interacting with the underlying -domain model, and stores the results in a bunch of variables, which represent -the new state of the View. The View then queries the Presentation Model to -retrieve these new values. In Maypole, this is the role of the C method -on L, which transmits the new values to the templates. +The user sends an event (e.g. an HTTP request) to the Controller. The Controller +translates the request into a method call on the Presentation Model. The +Presentation Model interacts with the underlying Domain Model, and stores the +results in a bunch of variables, which I +(that's why it's a Presentation Model, not a Domain Model). The View then +queries the Presentation Model to retrieve these new values. In Maypole, this is +the role of the C method on L, which transmits the +new values to the templates. =back -- 2.39.2