X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=lib%2FMaypole%2FManual%2FTerminology.pod;h=adc5dc85b64d017782b9db0d8d78d5d0d4739c0a;hb=1c8db728a3fb5adb4f0ea876ea1316457700edf8;hp=3e9a53ac0f64b0066d342f684298d1b9cc38f1c8;hpb=ac92533bb5ff5349e1936128d889e7a181dd224c;p=maypole.git diff --git a/lib/Maypole/Manual/Terminology.pod b/lib/Maypole/Manual/Terminology.pod index 3e9a53a..adc5dc8 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. @@ -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,18 +86,22 @@ 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 @@ -111,79 +119,84 @@ 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. See L. - -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. - -=item view +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. -This is represented in Maypole by the view class (L, -L, or L), and by the templates. +=back =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. - -=back +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