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 and 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 called a C<command>.\r
  98 \r
  99 =item template\r
 100 \r
 101 A file used to generate HTML for part or all of a web page. Maypole currently \r
 102 supports Template Toolkit and Mason as templating languages, but others could \r
 103 be added easily. Of course, a template doesn't have to generate only HTML.\r
 104 \r
 105 =back\r
 106 \r
 107 =head2 MVC and Maypole\r
 108 \r
 109 =head3 MVC - Model-View-Controller\r
 110 \r
 111 A pattern describing separation of concerns in a complex application. The \r
 112 C<model> represents the domain or business logic. The C<view> represents the \r
 113 user interface. The C<controller> mediates the interaction between the two. \r
 114 \r
 115 Opinions vary between how closely Maypole adheres to this pattern. \r
 116 \r
 117 Here's one opinion:\r
 118 \r
 119 =over 4 \r
 120 \r
 121 =item view\r
 122 \r
 123 This is represented in Maypole by the view class (L<Maypole::View::TT>, \r
 124 L<Maypole::View::Mason>, or L<MasonX::Maypole::View>), and by the templates. \r
 125 \r
 126 =item controller\r
 127 \r
 128 An abstract concept in Maypole, i.e. there is no specific controller class. \r
 129 \r
 130 The main sequence of events that occur during the processing of a request is\r
 131 controlled by methods in C<Maypole.pm>. Thus, major parts of the controller are\r
 132 in the same class as the request object. This may seem a bit strange, but in\r
 133 practice it works well.\r
 134 \r
 135 More detailed events within the processing of a request are actually handled by \r
 136 methods in the Maypole 'model'. For instance, switching from one template to \r
 137 another - the "Template Switcheroo" referred to in L<Maypole::Manual::Cookbook>. \r
 138 \r
 139 Be aware that occasionally authors refer to the C<controller> when they are\r
 140 describing the C<driver>.\r
 141 \r
 142 =item model\r
 143 \r
 144 In Maypole, the model is the set of classes representing individual tables in \r
 145 the database. Tables are related to each other in a more or less complex \r
 146 way. Each table class inherits from a Maypole model class, such as \r
 147 L<Maypole::Model::CDBI> or L<Maypole::Model::CDBI::Plain>. \r
 148 \r
 149 In fact, much of the functionality provided by the Maypole model class, may be \r
 150 better thought of as being controller code. And much of the custom code written \r
 151 by developers to support specific applications, is in fact controller code. \r
 152 \r
 153 The distinction is probably unimportant when using Maypole in 'default' mode - \r
 154 i.e. using L<Maypole::Model::CDBI>, and allowing Maypole to autogenerate the \r
 155 'model' classes straight out of the database. \r
 156 \r
 157 However, in many applications, a more complex domain model is required, or may\r
 158 already exist (see L<Maypole::Manual::Inheritance>). In this case, the Maypole\r
 159 model is more clearly seen as a layer that sits on top of the custom domain\r
 160 model, and controls access to it from the web UI. In this kind of situation, it\r
 161 seems more helpful to think of the Maypole model as part of the controller (or\r
 162 as a Presentation Model - see below).\r
 163 \r
 164 This conceptualisation helps developers maintain a separation between the\r
 165 Maypole model classes, and their own domain model. Without this distinction,\r
 166 developers may add domain-specific code to the Maypole model classes. To a\r
 167 certain extent, this is fine. But if you find yourself adding lots of\r
 168 non-Exported methods to your Maypole model classes, and these methods are not\r
 169 there to directly support Exported methods, consider whether you could separate\r
 170 out the domain model into a separate hierarchy of classes that you import into\r
 171 the Maypole model. See L<Maypole::Manual::Inheritance>.\r
 172 \r
 173 Otherwise, there will be two uncoupled code bases, living in the same files,\r
 174 interacting through a relatively small number of methods. These methods should\r
 175 in fact become the public API of the domain model, which should be moved to a\r
 176 separate class hierarchy.\r
 177 \r
 178 The distinction between the Maypole model, the domain model, and the model in \r
 179 the MVC pattern, is fuzzy and variable. In straightforward Maypole applications, \r
 180 they're all pretty much the same thing. In more advanced applications, they \r
 181 begin to diverge. See C<Presentation Model>.  \r
 182 \r
 183 =head3 Presentation Model\r
 184 \r
 185 This pattern seems to more accurately describe the role of the Maypole model.\r
 186 Martin Fowler describes I<Presentation Model> in L<Separting presentation logic\r
 187 from the View|http://www.martinfowler.com/eaaDev/OrganizingPresentations.html>\r
 188 and L<Presentation\r
 189 Model|http://www.martinfowler.com/eaaDev/PresentationModel.html>.\r
 190 \r
 191 The View sends events (e.g. an HTTP request that triggers an Exported method) to\r
 192 the Presentation Model. This layer responds by interacting with the underlying\r
 193 domain model, and stores the results in a bunch of variables, which represent\r
 194 the new state of the View. The View then queries the Presentation Model to\r
 195 retrieve these new values. In Maypole, this is the role of the C<vars()> method \r
 196 on L<Maypole::View::Base>, which transmits the new values to the templates. \r
 197 \r
 198 =back\r
 199 \r
 200 =head1 AUTHOR\r
 201 \r
 202 David Baird, C<< <cpan@riverside-cms.co.uk> >>\r
 203 \r
 204 =head1 COPYRIGHT & LICENSE\r
 205 \r
 206 Copyright 2005 David Baird, All Rights Reserved.\r
 207 \r
 208 This text is free documentation; you can redistribute it and/or modify it\r
 209 under the same terms as the Perl documentation itself.\r
 210 \r
 211 =cut\r