--- /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 application\r
+\r
+Sometimes this is used to refer to the driver, but this term is best reserved \r
+to refer to the complete application, i.e. driver, plugins, templates, model, \r
+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 and 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. \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: not the action attribute of a form, although the form's action URI will \r
+generally include a Maypole action component.\r
+\r
+=item command\r
+\r
+In some templates, an C<action> is called a 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.\r
+\r
+=head2 MVC and Maypole\r
+\r
+=item 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 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 L<Maypole>. Thus, major parts of the controller are in \r
+the same class as the request object. This may seem a bit strange, but in \r
+practice 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. \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 \r
+way. Each table class inherits from a Maypole model class, such as \r
+L<Maypole::Model::CDBI> or L<Maypole::Model::CDBI::Plain>. \r
+\r
+In fact, much of the functionality provided by the Maypole model class, may be \r
+better thought of as being controller code. And much of the custom code written \r
+by developers to support specific applications, is in fact controller code. \r
+\r
+The distinction is probably 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 custom domain model, and controls access to it from \r
+the web UI. In this kind of situation, it seems more helpful to think of the \r
+Maypole model as part of the controller. This conceptualisation helps developers \r
+maintain a separation between the Maypole model classes, and their own domain \r
+model. Without this distinction, developers may add domain-specific code \r
+to the Maypole model classes, ending up with two separate code bases \r
+intermingled within one set of files. \r
+\r
+To a certain extent, this is fine. But if you find yourself adding lots on \r
+non-Exported methods to your Maypole model classes, \r
+and these methods are not there to support Exported methods, consider whether \r
+you could separate out the domain model into a separate hierarchy of classes \r
+that you import into the Maypole model. \r
+\r
+The distinction between the Maypole model, the domain model, and the model in \r
+the MVC pattern, is fuzzy and variable. In straightforward Maypole applications, \r
+they're all pretty much the same thing. In more advanced applications, they \r
+begin to diverge. Take care out there. \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
+\r
+=back\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