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, but this term is best reserved \r
  34 to refer to the complete application, i.e. driver, plugins, templates, model, \r
  35 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 =over 4\r
 103 \r
 104 =item MVC - Model-View-Controller\r
 105 \r
 106 A pattern describing separation of concerns in a complex application. The \r
 107 C<model> represents the domain or business logic. The C<view> represents the \r
 108 user interface. The C<controller> mediates the interaction between the two. \r
 109 \r
 110 Opinions vary between how closely Maypole adheres to this pattern. \r
 111 \r
 112 Here's one opinion:\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, \r
 157 and these methods are not there to support Exported methods, consider whether \r
 158 you could separate out the domain model into a separate hierarchy of classes \r
 159 that you import into the Maypole model. \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. Take care out there. \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 \r
 172 =back\r
 173 \r
 174 =head1 AUTHOR\r
 175 \r
 176 David Baird, C<< <cpan@riverside-cms.co.uk> >>\r
 177 \r
 178 =head1 COPYRIGHT & LICENSE\r
 179 \r
 180 Copyright 2005 David Baird, All Rights Reserved.\r
 181 \r
 182 This text is free documentation; you can redistribute it and/or modify it\r
 183 under the same terms as the Perl documentation itself.\r
 184 \r
 185 =cut\r