lib/Maypole/Manual/Terminology.pod

   1 =head1 NAME\r
   2 \r
   3 Maypole::Manual::Terminology - common terms\r
   4 \r
   5 =head1 VERSION\r
   6 \r
   7 This version written for Maypole 2.11\r
   8 \r
   9 =head1 TERMINOLOGY\r
  10 \r
  11 For the avoidance of confusion, the following terms are defined. We'll try and \r
  12 ensure the Maypole docs stick to these usages.\r
  13 \r
  14 =over 4\r
  15 \r
  16 =item driver\r
  17 \r
  18 The custom package written to set up a Maypole application. This is the package \r
  19 that has the C<use Maypole::Application> statement. If you're not using \r
  20 L<Maypole::Application> to set up your app (not recommended for newbies, but \r
  21 common enough), the driver class will directly inherit from one of Maypole's \r
  22 frontend classes. \r
  23 \r
  24 =item controller\r
  25 \r
  26 Occasionally this term is used in place of C<driver>.\r
  27 \r
  28 See the entry below (MVC) for the main usage of the term C<controller> within \r
  29 Maypole. \r
  30 \r
  31 =item application\r
  32 \r
  33 Sometimes this is used to refer to the driver, or the driver plus configuration\r
  34 data, but this term is best reserved to refer to the complete application, i.e.\r
  35 driver, plugins, templates, model, config, the whole shebang.\r
  36 \r
  37 =item frontend\r
  38 \r
  39 An adapter class that allows Maypole to work in a number of different server \r
  40 environments. The currently available frontends are:\r
  41 \r
  42     Frontend        Distribution    Environment\r
  43     ==============================================\r
  44     CGI::Maypole    Maypole         CGI\r
  45     Apache::MVC     Maypole         Apache/mod_perl or Apache2/mod_perl2\r
  46     MasonX::Maypole     MasonX::Maypole Apache/mod_perl with Mason\r
  47         \r
  48 The driver class inherits from the appropriate frontend, which inherits from \r
  49 L<Maypole>.\r
  50         \r
  51 =item backend\r
  52 \r
  53 Confusingly, sometimes you'll see the frontend referred to as the backend. It \r
  54 depends on your point of view.\r
  55 \r
  56 Also confusingly, the Maypole model (e.g. L<Maypole::Model::CDBI>) is sometimes\r
  57 referred to as the backend.\r
  58 \r
  59 You'll just need to pay attention to context. In general, it's probably best to \r
  60 avoid using this term altogether. \r
  61 \r
  62 =item request\r
  63 \r
  64 The Maypole request object. This contains all data sent in the request\r
  65 (including headers, cookies, CGI parameters), and accumulates data to be sent in\r
  66 the response (headers and content). It also provides access to the configuration\r
  67 object, and stores the information parsed out of the URL (action, table, args\r
  68 etc.). Plugins often add methods and further data members to the request object. \r
  69 \r
  70 =item workflow\r
  71 \r
  72 The sequence of events when a browser sends a request to a Maypole \r
  73 application. \r
  74 \r
  75 You will also often see this referred to as the C<request> (distinct from the \r
  76 request object).\r
  77 \r
  78 =item Exported method\r
  79 \r
  80 A method in a Maypole model class that is labelled with the C<Exported> \r
  81 attribute. These methods are mapped to part of the request URI. So requesting \r
  82 a path will result in a particular method being called on a particular model \r
  83 class.\r
  84 \r
  85 =item action\r
  86 \r
  87 An Exported method.\r
  88 \r
  89 Note: this is not the action attribute of a form, although the form's action URI\r
  90 will generally include a Maypole action component. For instance, a form might\r
  91 submit to the following URL: C<[% $base %]/beer/drink/5>. The form action is the\r
  92 URL, whereas the Maypole action is the C<drink> method on the C<BeerDB::Beer>\r
  93 object with an ID of 5.\r
  94 \r
  95 =item command\r
  96 \r
  97 In some of the standard factory templates, an C<action> is referred to as a \r
  98 C<command>.\r
  99 \r
 100 =item template\r
 101 \r
 102 A file used to generate HTML for part or all of a web page. Maypole currently \r
 103 supports Template Toolkit and Mason as templating languages, but others could \r
 104 be added easily. Of course, a template doesn't have to generate only HTML.\r
 105 \r
 106 =back\r
 107 \r
 108 =head2 MVC and Maypole\r
 109 \r
 110 =head3 MVC - Model-View-Controller\r
 111 \r
 112 A pattern describing separation of concerns in a complex application. The \r
 113 C<model> represents the domain or business logic. The C<view> represents the \r
 114 user interface. The C<controller> mediates the interaction between the two. \r
 115 \r
 116 Opinions vary between how closely Maypole adheres to this pattern. \r
 117 \r
 118 Here's one opinion:\r
 119 \r
 120 =over 4 \r
 121 \r
 122 =item view\r
 123 \r
 124 This is represented in Maypole by the view class (L<Maypole::View::TT>, \r
 125 L<Maypole::View::Mason>, or L<MasonX::Maypole::View>), and by the templates. \r
 126 \r
 127 =item controller\r
 128 \r
 129 An abstract concept in Maypole, i.e. there is no specific controller class. \r
 130 \r
 131 The main sequence of events that occur during the processing of a request is\r
 132 controlled by methods in C<Maypole.pm>. Thus, the controller logic is in the\r
 133 same class as the request object. This may seem a bit strange, but in practice\r
 134 it works well.\r
 135 \r
 136 More detailed events within the processing of a request are actually handled by \r
 137 methods in the Maypole 'model'. For instance, switching from one template to \r
 138 another - the "Template Switcheroo" referred to in L<Maypole::Manual::Cookbook>. \r
 139 \r
 140 Be aware that occasionally authors refer to the C<controller> when they are\r
 141 describing the C<driver>.\r
 142 \r
 143 =item model\r
 144 \r
 145 In Maypole, the 'model' is the set of classes representing individual tables in\r
 146 the database. Tables are related to each other in a more or less complex way.\r
 147 Each table class inherits from a Maypole model class, such as\r
 148 L<Maypole::Model::CDBI> or L<Maypole::Model::CDBI::Plain>.\r
 149 \r
 150 The functionality provided by the Maypole model class is more accurately\r
 151 described as a Presentation Model (see below). In complex Maypole applications,\r
 152 it is good practise to separate the domain model (the 'heart' of the\r
 153 application) into a separate class hierarchy (see\r
 154 L<Maypole::Manual::Inheritance>).\r
 155 \r
 156 The distinction is relatively unimportant when using Maypole in 'default' mode - \r
 157 i.e. using L<Maypole::Model::CDBI>, and allowing Maypole to autogenerate the \r
 158 'model' classes straight out of the database. \r
 159 \r
 160 However, in many applications, a more complex domain model is required, or may\r
 161 already exist. In this case, the Maypole model is more clearly seen as a layer\r
 162 that sits on top of the domain model, mediating access to it from the web UI, \r
 163 via the controller.\r
 164 \r
 165 This conceptualisation helps developers maintain a separation between the\r
 166 Maypole model classes (presentation model), and the domain model. Without this\r
 167 distinction, developers may add domain-specific code to the Maypole model\r
 168 classes. To a certain extent, in simple applications, this is fine. But if you\r
 169 find yourself adding lots of non-Exported methods to your Maypole model classes,\r
 170 and these methods are not there to directly support Exported methods, consider\r
 171 whether you could separate out the domain model into a separate hierarchy of\r
 172 classes - see L<Maypole::Manual::Inheritance>.\r
 173 \r
 174 Otherwise, the 'model' classes may develop into two quite uncoupled code bases,\r
 175 but which co-exist in the same files. They will interact through a relatively\r
 176 small number of methods. These methods should in fact become the public API of\r
 177 the domain model, which should be moved to a separate class hierarchy. At some\r
 178 point, the convenience of dropping new methods into the 'shared' classes will be\r
 179 outweighed by the heuristic advantage of separating different layers into\r
 180 separate class hierarchies.\r
 181 \r
 182 =back\r
 183 \r
 184 =head3 Presentation Model\r
 185 \r
 186 This pattern more accurately describes the role of the Maypole model.\r
 187 Martin Fowler describes I<Presentation Model> in L<Separting presentation logic\r
 188 from the View|http://www.martinfowler.com/eaaDev/OrganizingPresentations.html>\r
 189 and L<Presentation\r
 190 Model|http://www.martinfowler.com/eaaDev/PresentationModel.html>.\r
 191 \r
 192 The user sends an event (e.g. an HTTP request) to the Controller. The Controller\r
 193 translates the request into a method call on the Presentation Model. The\r
 194 Presentation Model interacts with the underlying Domain Model, and stores the\r
 195 results in a bunch of variables, which I<represent the new state of the View>\r
 196 (that's why it's a Presentation Model, not a Domain Model). The View then\r
 197 queries the Presentation Model to retrieve these new values. In Maypole, this is\r
 198 the role of the C<vars()> method on L<Maypole::View::Base>, which transmits the\r
 199 new values to the templates.\r
 200 \r
 201 =head1 AUTHOR\r
 202 \r
 203 David Baird, C<< <cpan@riverside-cms.co.uk> >>\r
 204 \r
 205 =head1 COPYRIGHT & LICENSE\r
 206 \r
 207 Copyright 2005 David Baird, All Rights Reserved.\r
 208 \r
 209 This text is free documentation; you can redistribute it and/or modify it\r
 210 under the same terms as the Perl documentation itself.\r
 211 \r
 212 =cut\r