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 application\r
  25 \r
  26 Sometimes this is used to refer to the driver, but this term is best reserved \r
  27 to refer to the complete application, i.e. driver, plugins, templates, model, \r
  28 the whole shebang.\r
  29 \r
  30 =item frontend\r
  31 \r
  32 An adapter class that allows Maypole to work in a number of different server \r
  33 environments. The currently available frontends are:\r
  34 \r
  35         Frontend        Distribution       Environment\r
  36         ==============================================\r
  37         CGI::Maypole    Maypole            CGI\r
  38         Apache::MVC     Maypole            Apache/mod_perl and Apache2/mod_perl2\r
  39         MasonX::Maypole MasonX::Maypole    Apache/mod_perl with Mason\r
  40         \r
  41 The driver class inherits from the appropriate frontend, which inherits from \r
  42 L<Maypole>.\r
  43         \r
  44 =item backend\r
  45 \r
  46 Confusingly, sometimes you'll see the frontend referred to as the backend. It \r
  47 depends on your point of view.\r
  48 \r
  49 Also confusingly, the Maypole model (e.g. L<Maypole::Model::CDBI>) is sometimes\r
  50 referred to as the backend.\r
  51 \r
  52 You'll just need to pay attention to context. In general, it's probably best to \r
  53 avoid using this term altogether. \r
  54 \r
  55 =item request\r
  56 \r
  57 The Maypole request object. \r
  58 \r
  59 =item workflow\r
  60 \r
  61 The sequence of events when a browser sends a request to a Maypole \r
  62 application. \r
  63 \r
  64 You will also often see this referred to as the C<request> (distinct from the \r
  65 request object).\r
  66 \r
  67 =item Exported method\r
  68 \r
  69 A method in a Maypole model class that is labelled with the C<Exported> \r
  70 attribute. These methods are mapped to part of the request URI. So requesting \r
  71 a path will result in a particular method being called on a particular model \r
  72 class.\r
  73 \r
  74 =item action\r
  75 \r
  76 An Exported method.\r
  77 \r
  78 Note: not the action attribute of a form, although the form's action URI will \r
  79 generally include a Maypole action component.\r
  80 \r
  81 =item command\r
  82 \r
  83 In some templates, an C<action> is called a C<command>.\r
  84 \r
  85 =item template\r
  86 \r
  87 A file used to generate HTML for part or all of a web page. Maypole currently \r
  88 supports Template Toolkit and Mason as templating languages, but others could \r
  89 be added easily.\r
  90 \r
  91 =head2 MVC and Maypole\r
  92 \r
  93 =item MVC - Model-View-Controller\r
  94 \r
  95 A pattern describing separation of concerns in a complex application. The \r
  96 C<model> represents the domain or business logic. The C<view> represents the \r
  97 user interface. The C<controller> mediates the interaction between the two. \r
  98 \r
  99 Opinions vary between how closely Maypole adheres to this pattern. \r
 100 \r
 101 Here's one opinion:\r
 102 \r
 103 =over 4\r
 104 \r
 105 =item controller\r
 106 \r
 107 An abstract concept in Maypole, i.e. there is no specific controller class. \r
 108 \r
 109 The main sequence of events that occur during the processing of a request is \r
 110 controlled by methods in L<Maypole>. Thus, major parts of the controller are in \r
 111 the same class as the request object. This may seem a bit strange, but in \r
 112 practice it works well.\r
 113 \r
 114 More detailed events within the processing of a request are actually handled by \r
 115 methods in the Maypole 'model'. For instance, switching from one template to \r
 116 another. \r
 117 \r
 118 =item model\r
 119 \r
 120 In Maypole, the model is the set of classes representing individual tables in \r
 121 the database. Tables are related to each other in a more or less complex \r
 122 way. Each table class inherits from a Maypole model class, such as \r
 123 L<Maypole::Model::CDBI> or L<Maypole::Model::CDBI::Plain>. \r
 124 \r
 125 In fact, much of the functionality provided by the Maypole model class, may be \r
 126 better thought of as being controller code. And much of the custom code written \r
 127 by developers to support specific applications, is in fact controller code. \r
 128 \r
 129 The distinction is probably unimportant when using Maypole in 'default' mode - \r
 130 i.e. using L<Maypole::Model::CDBI>, and allowing Maypole to autogenerate the \r
 131 'model' classes straight out of the database. \r
 132 \r
 133 However, in many applications, a more complex domain model is required, or may \r
 134 already exist. In this case, the Maypole model is more clearly seen as a layer \r
 135 that sits on top of the custom domain model, and controls access to it from \r
 136 the web UI. In this kind of situation, it seems more helpful to think of the \r
 137 Maypole model as part of the controller. This conceptualisation helps developers \r
 138 maintain a separation between the Maypole model classes, and their own domain \r
 139 model. Without this distinction, developers may add domain-specific code \r
 140 to the Maypole model classes, ending up with two separate code bases \r
 141 intermingled within one set of files. \r
 142 \r
 143 To a certain extent, this is fine. But if you find yourself adding lots on \r
 144 non-Exported methods to your Maypole model classes, \r
 145 and these methods are not there to support Exported methods, consider whether \r
 146 you could separate out the domain model into a separate hierarchy of classes \r
 147 that you import into the Maypole model. \r
 148 \r
 149 The distinction between the Maypole model, the domain model, and the model in \r
 150 the MVC pattern, is fuzzy and variable. In straightforward Maypole applications, \r
 151 they're all pretty much the same thing. In more advanced applications, they \r
 152 begin to diverge. Take care out there. \r
 153 \r
 154 =item view\r
 155 \r
 156 This is represented in Maypole by the view class (L<Maypole::View::TT>, \r
 157 L<Maypole::View::Mason>, or L<MasonX::Maypole::View>), and by the templates. \r
 158 \r
 159 \r
 160 =back\r
 161 \r
 162 =head1 AUTHOR\r
 163 \r
 164 David Baird, C<< <cpan@riverside-cms.co.uk> >>\r
 165 \r
 166 =head1 COPYRIGHT & LICENSE\r
 167 \r
 168 Copyright 2005 David Baird, All Rights Reserved.\r
 169 \r
 170 This text is free documentation; you can redistribute it and/or modify it\r
 171 under the same terms as the Perl documentation itself.\r
 172 \r
 173 =cut\r