X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=lib%2FMaypole%2FManual%2FTerminology.pod;h=adc5dc85b64d017782b9db0d8d78d5d0d4739c0a;hb=1c8db728a3fb5adb4f0ea876ea1316457700edf8;hp=1871910c3b232cb4e60493b314881d878de744ac;hpb=ad24ffc85f25a9b73a28cd326c3b3caea234adbf;p=maypole.git diff --git a/lib/Maypole/Manual/Terminology.pod b/lib/Maypole/Manual/Terminology.pod index 1871910..adc5dc8 100644 --- a/lib/Maypole/Manual/Terminology.pod +++ b/lib/Maypole/Manual/Terminology.pod @@ -30,20 +30,20 @@ Maypole. =item application -Sometimes this is used to refer to the driver, but this term is best reserved -to refer to the complete application, i.e. driver, plugins, templates, model, -the whole shebang. +Sometimes this is used to refer to the driver, or the driver plus configuration +data, but this term is best reserved to refer to the complete application, i.e. +driver, plugins, templates, model, config, the whole shebang. =item frontend 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. @@ -61,7 +61,11 @@ avoid using this term altogether. =item request -The Maypole request object. +The Maypole request object. This contains all data sent in the request +(including headers, cookies, CGI parameters), and accumulates data to be sent in +the response (headers and content). It also provides access to the configuration +object, and stores the information parsed out of the URL (action, table, args +etc.). Plugins often add methods and further data members to the request object. =item workflow @@ -82,26 +86,28 @@ class. An Exported method. -Note: not the action attribute of a form, although the form's action URI will -generally include a Maypole action component. +Note: this is not the action attribute of a form, although the form's action URI +will generally include a Maypole action component. For instance, a form might +submit to the following URL: C<[% $base %]/beer/drink/5>. The form action is the +URL, whereas the Maypole action is the C method on the C +object with an ID of 5. =item command -In some templates, an C is called a C. +In some of the standard factory templates, an C is referred to as a +C. =item template 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 -be added easily. +be added easily. Of course, a template doesn't have to generate only HTML. =back =head2 MVC and Maypole -=over 4 - -=item MVC - Model-View-Controller +=head3 MVC - Model-View-Controller A pattern describing separation of concerns in a complex application. The C represents the domain or business logic. The C represents the @@ -111,66 +117,87 @@ Opinions vary between how closely Maypole adheres to this pattern. Here's one opinion: +=over 4 + +=item view + +This is represented in Maypole by the view class (L, +L, or L), and by the templates. + =item controller 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 -another. +another - the "Template Switcheroo" referred to in L. Be aware that occasionally authors refer to the C when they are 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). -The distinction is probably unimportant when using Maypole in 'default' mode - +The distinction is relatively unimportant when using Maypole in 'default' mode - i.e. using 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. 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. 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, ending up with two separate code bases -intermingled within one set of files. - -To a certain extent, this is fine. But if you find yourself adding lots on -non-Exported methods to your Maypole model classes, -and these methods are not there to 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. - -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. Take care out there. - -=item view - -This is represented in Maypole by the view class (L, -L, or L), and by the templates. - +However, in many applications, a more complex domain model is required, or may +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 (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. =back +=head3 Presentation Model + +This pattern more accurately describes the role of the Maypole model. +Martin Fowler describes I in L +and L. + +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. + =head1 AUTHOR David Baird, C<< >>