X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;ds=sidebyside;f=lib%2FMaypole%2FManual%2FTerminology.pod;h=d7bf7f433e315a4d9f0827328df1e18438518517;hb=f4a654d5fee1b79ced98bb6d71a4f3b4bf402ecd;hp=0ef3581fff9e9077fb5287d1c97da8aad34ff0d5;hpb=9a7acdd3a2e0701d2fe5366e4965c030a530f860;p=maypole.git 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