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