--- /dev/null
+=head1 NAME\r
+\r
+Maypole::Manual::Terminology - common terms\r
+\r
+=head1 VERSION\r
+\r
+This version written for Maypole 2.11\r
+\r
+=head1 TERMINOLOGY\r
+\r
+For the avoidance of confusion, the following terms are defined. We'll try and \r
+ensure the Maypole docs stick to these usages.\r
+\r
+=over 4\r
+\r
+=item driver\r
+\r
+The custom package written to set up a Maypole application. This is the package \r
+that has the C<use Maypole::Application> statement. If you're not using \r
+L<Maypole::Application> to set up your app (not recommended for newbies, but \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
+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
+ 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
+=item backend\r
+\r
+Confusingly, sometimes you'll see the frontend referred to as the backend. It \r
+depends on your point of view.\r
+\r
+Also confusingly, the Maypole model (e.g. L<Maypole::Model::CDBI>) is sometimes\r
+referred to as the backend.\r
+\r
+You'll just need to pay attention to context. In general, it's probably best to \r
+avoid using this term altogether. \r
+\r
+=item request\r
+\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
+The sequence of events when a browser sends a request to a Maypole \r
+application. \r
+\r
+You will also often see this referred to as the C<request> (distinct from the \r
+request object).\r
+\r
+=item Exported method\r
+\r
+A method in a Maypole model class that is labelled with the C<Exported> \r
+attribute. These methods are mapped to part of the request URI. So requesting \r
+a path will result in a particular method being called on a particular model \r
+class.\r
+\r
+=item action\r
+\r
+An Exported method.\r
+\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
+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
+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
+=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
+user interface. The C<controller> mediates the interaction between the two. \r
+\r
+Opinions vary between how closely Maypole adheres to this pattern. \r
+\r
+Here's one opinion:\r
+\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
+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
+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
+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
+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
+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
+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
+=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
+\r
+=head1 COPYRIGHT & LICENSE\r
+\r
+Copyright 2005 David Baird, All Rights Reserved.\r
+\r
+This text is free documentation; you can redistribute it and/or modify it\r
+under the same terms as the Perl documentation itself.\r
+\r
+=cut\r
projects / maypole.git / blobdiff