lib/Maypole/Manual/Inheritance.pod

   1 \r
   2 =head1 NAME\r
   3 \r
   4 Maypole::Manual::Inheritance - structure of a Maypole application\r
   5 \r
   6 =head1 DESCRIPTION\r
   7 \r
   8 Discusses the inheritance structure of a basic and a more advanced Maypole\r
   9 application.\r
  10 \r
  11 =head1 CONVENTIONS\r
  12           \r
  13 =over 4\r
  14 \r
  15 =item inheritance\r
  16 \r
  17         +\r
  18         |\r
  19     +--  --+\r
  20         |\r
  21         |\r
  22         +\r
  23         \r
  24 =item notes\r
  25 \r
  26     target *-------- note about the target\r
  27 \r
  28 =item association\r
  29 \r
  30     source ------> target\r
  31 \r
  32 =back\r
  33 \r
  34 =head1 A standard Maypole application\r
  35 \r
  36 A minimal Maypole application (such as the Beer database) consists of a \r
  37 custom driver class (BeerDB.pm), a set of auto-generated model classes, and a \r
  38 view class: \r
  39 \r
  40 \r
  41                   THE DRIVER\r
  42                                           +------- init() is a factory method,\r
  43                    1      Maypole         |           it sets up the view\r
  44    Maypole::Config <----- config();       |              classes\r
  45    model();               init(); *-------+                           THE VIEW\r
  46     |                     view_object(); -------+\r
  47     |    +--------------* setup();              |      Maypole::View::Base\r
  48     |    |                   +                  |              +\r
  49     |    |                   |                  |     1        |\r
  50     |    |    PLUGINS    Apache::MVC *-----+    +-----> Maypole::View::TT\r
  51     |    |       +           +             |             (or another view class)\r
  52     |    |       |           |             |\r
  53     |    |       +-----+-----+             |\r
  54     |    |             |                   |\r
  55     |    |           BeerDB                +----- or CGI::Maypole\r
  56     |    |                                         or MasonX:::Maypole\r
  57     |    |\r
  58     |   setup() is a factory method,\r
  59     |     it sets up the model\r
  60     |         classes\r
  61     |\r
  62     |                                 THE MODEL\r
  63     |\r
  64     |  Maypole::Model::Base   Class::DBI\r
  65     |             +             +\r
  66     |             |             |\r
  67     +-------> Maypole::Model::CDBI\r
  68                       +\r
  69                       |\r
  70            +------------+--------+-------+---------+\r
  71            |            |        |       |         |\r
  72        BeerDB::Pub      |   BeerDB::Beer | BeerDB::Brewery\r
  73        beers();         |   pubs();      | beers();\r
  74                         |   brewery();   |\r
  75                         |   style();     |\r
  76           BeerDB::Handpump               |\r
  77           pub();                      BeerDB::Style\r
  78           beer();                     beers();\r
  79 \r
  80 =head2 What about Maypole::Application - loading plugins\r
  81 \r
  82 The main job of L<Maypole::Application> is to insert the plugins into the\r
  83 hierarchy. It is also the responsibility of L<Maypole::Application> to decide\r
  84 which frontend to use. It builds the list of plugins, then pushes them onto the\r
  85 driver's C<@ISA>, then pushes the frontend onto the end of the driver's C<@ISA>.\r
  86 So method lookup first searches all the plugins, before searching the frontend\r
  87 and finally L<Maypole> itself.\r
  88 \r
  89 From Maypole 2.11, L<Maypole::Application> makes no appearance in the\r
  90 inheritance structure of a Maypole application. (In prior versions,\r
  91 L<Maypole::Application> would make itself inherit the plugins, and then insert\r
  92 itself in the hierarchy, but this was unnecessary).\r
  93 \r
  94 =head2 Who builds the model?\r
  95 \r
  96 First, remember we are talking about the standard, unmodified Maypole here. \r
  97 It is possible, and common, to override some or all of this stage and build a \r
  98 customised model.\r
  99 \r
 100 The standard model is built in 3 stages. \r
 101 \r
 102 First, C<Maypole::setup> calls C<setup_database> on the Maypole model class, in\r
 103 this case L<Maypole::Model::CDBI>. C<setup_database> then uses\r
 104 L<Class::DBI::Loader> to autogenerate individual L<Class::DBI> classes for each\r
 105 of the tables in the database (C<BeerDB::Beer>, C<BeerDB::Pub> etc).\r
 106 \r
 107 Next, C<Maypole::setup> B<unshifts> L<Maypole::Model::CDBI> onto the C<@ISA> \r
 108 array of each of these classes. \r
 109 \r
 110 Finally, the relationships among these tables are set up. Either do this\r
 111 manually, perhaps with the help of L<Class::DBI::Relationship>, or use\r
 112 L<Maypole::Plugin::Relationship>. In the latter case, you need to set up the\r
 113 relationships configuration before calling C<setup()>.\r
 114 \r
 115 \r
 116 =head1 An advanced Maypole application\r
 117 \r
 118 We'll call it C<BeerDB2>.\r
 119 \r
 120 Maypole is a framework, and you can replace different bits as you wish. So what \r
 121 follows is one example of good practice, other people may do things differently. \r
 122 \r
 123 We assume this application is being built from the ground up, but it will often\r
 124 be straightforward to adapt an existing L<Class::DBI> application to this\r
 125 general model.\r
 126 \r
 127 The main idea is that the autogenerated Maypole model is used as a layer on top\r
 128 of a separate L<Class::DBI> model. I am going to refer to this model as the\r
 129 'Offline' model, and the Maypole classes as the 'Maypole' model. The idea is\r
 130 that the Offline model can (potentially or in actuality) be used as part of\r
 131 another application, perhaps a command line program or a cron script, whatever.\r
 132 The Offline model does not know about the Maypole model, whereas the Maypole\r
 133 model does know about the Offline model.\r
 134 \r
 135 Let's call the offline model C<OfflineBeer>. As a traditional L<Class::DBI>\r
 136 application, individual table classes in this model will inherit from a common\r
 137 base (C<OfflineBeer>), which inherits from L<Class::DBI>).\r
 138 \r
 139 One advantage of this approach is that you can still use Maypole's autogenerated\r
 140 model. Another is that you do not mix online and offline code in the same\r
 141 packages.\r
 142 \r
 143 =head2 Building it\r
 144 \r
 145 Build a driver in a similar way as for the basic app, calling C<setup()> after\r
 146 setting up all the configuration. \r
 147 \r
 148 It is a good habit to use a custom Maypole model class for each application, as\r
 149 it's a likely first target for customisation. Start it like this:\r
 150 \r
 151     package BeerDB2::Maypole::Model;\r
 152     use strict;\r
 153     use warnings;\r
 154     use base 'Maypole::Model::CDBI';\r
 155     1;\r
 156     \r
 157 You can add methods which should be shared by all table classes to this package \r
 158 as and when required.\r
 159     \r
 160 Configure it like this, before the C<setup()> call in the driver class:\r
 161 \r
 162     # in package BeerDB2\r
 163     __PACKAGE__->config->model('BeerDB2::Maypole::Model');\r
 164     __PACKAGE__->setup;\r
 165 \r
 166 The C<setup()> call will ensure your custom model is loaded via C<require>.\r
 167 \r
 168 B<Note>: by default, this will create Maypole/CDBI classes for all the tables in\r
 169 the database. You can control this by passing options for L<Class::DBI::Loader>\r
 170 in the call to C<setup()>.\r
 171 \r
 172 For each class in the model, you need to create a separate file. So for\r
 173 C<BeerDB2::Beer>, you would write:\r
 174 \r
 175     package BeerDB2::Beer;\r
 176     use strict;\r
 177     use warnings;\r
 178     use base 'OfflineBeer::Beer';\r
 179     1;\r
 180     \r
 181 This package will be loaded automatically during C<setup()>, and\r
 182 C<BeerDB2::Maypole::Model> is B<unshifted> onto it's C<@ISA>. \r
 183 \r
 184 Configure relationships either in the individual C<OfflineBeer::*> classes, or\r
 185 else all together in C<OfflineBeer> itself i.e. not in the Maypole model. This \r
 186 way, you only define the relationships in one place.\r
 187 \r
 188 The resulting model looks like this:\r
 189 \r
 190                                        Class::DBI\r
 191     MAYPOLE 'MODEL'                       |\r
 192                                           |\r
 193    Maypole::Model::Base                   |\r
 194            +                              |\r
 195            |       +----------------------+-----------------+\r
 196            |       |                                        |\r
 197            |       |                                        |\r
 198      Maypole::Model::CDBI                                   |     OFFLINE\r
 199              +                                              |        MODEL\r
 200              |                                              |\r
 201      BeerDB2::Maypole::Model                           OfflineBeer\r
 202        +                                                    +\r
 203        |                                                    |\r
 204        |                                                    |\r
 205        +--- BeerDB2::Pub --------+ OfflineBeer::Pub --------+\r
 206        |                           beers();                 |\r
 207        |                                                    |\r
 208        |                           OfflineBeer::Handpump ---+\r
 209        |                           beer();                  |\r
 210        |                           pub();                   |\r
 211        |                                                    |\r
 212        +--- BeerDB2::Beer -------+ OfflineBeer::Beer -------+\r
 213        |                           pubs();                  |\r
 214        |                           brewery();               |\r
 215        |                           style();                 |\r
 216        |                                                    |\r
 217        +--- BeerDB2::Style ------+ OfflineBeer::Style ------+\r
 218        |                           beers();                 |\r
 219        |                                                    |\r
 220        +--- BeerDB2::Brewery ----+ OfflineBeer::Brewery ----+\r
 221                                    beers();\r
 222 \r
 223 \r
 224 \r
 225 =head3 Features\r
 226 \r
 227 Non-Maypole applications using the Offline model are completely isolated from\r
 228 the Maypole application, and need not know it exists at all.\r
 229 \r
 230 Methods defined in the Maypole table classes, override methods defined in the\r
 231 Offline table classes, because C<BeerDB2::Maypole::Model> was unshifted onto the\r
 232 beginning of each Maypole table class's C<@ISA>. Perl's depth first,\r
 233 left-to-right method lookup from e.g. C<BeerDB2::Beer> starts in\r
 234 C<BeerDB2::Beer>, then C<BeerDB2::Maypole::Model>, C<Maypole::Model::CDBI>,\r
 235 C<Maypole::Model::Base>, and C<Class::DBI>, before moving on to\r
 236 C<OfflineBeer::Beer> and finally C<OfflineBeer>.\r
 237 \r
 238 B<CAVEAT> - if your Offline model overrides L<Class::DBI> methods, these methods\r
 239 will B<not> be overridden when called from the Maypole application, because the\r
 240 Maypole model provides an alternative path to L<Class::DBI> which is searched\r
 241 first. The solution is to place such methods in a separate package, e.g.\r
 242 C<OfflineBeer::CDBI>. Place this B<first> in the C<@ISA> of both\r
 243 C<BeerDB2::Maypole::Model> and C<OfflineBeer>. Note that C<OfflineBeer::CDBI>\r
 244 does not itself need to inherit from L<Class::DBI>.\r
 245 \r
 246 Methods defined in the Maypole model base class (C<BeerDB2::Maypole::Model>),\r
 247 override methods in the individual Offline table classes, and in the Offline\r
 248 model base class (C<Offline>). \r
 249 \r
 250 Relationships defined in the Offline classes are inherited by the Maypole model.\r
 251 \r
 252 The Maypole model has full access to the underlying Offline model. \r
 253 \r
 254 =head3 Theory \r
 255 \r
 256 This layout illustrates more clearly why the Maypole model may be thought of as\r
 257 part of the controller, rather than part of the model of MVC. Its function is to \r
 258 mediate web requests, translating them into method calls on the Offline model, \r
 259 munging the results, and returning them via the Maypole request object. \r
 260 \r
 261 Another way of thinking about it is that Maypole implements a two-layer\r
 262 controller. The first layer translates a raw request into a single method call\r
 263 on the Maypole model layer, which then translates that call into one or more\r
 264 calls on the underlying model.\r
 265 \r
 266 Whatever label you prefer to use, this approach provides for clear separation of\r
 267 concerns between the underlying model and the web/user interface, and that's\r
 268 what it's all about.\r
 269           \r
 270 =head1 AUTHOR\r
 271 \r
 272 David Baird, C<< <cpan@riverside-cms.co.uk> >>\r
 273 \r
 274 =head1 COPYRIGHT & LICENSE\r
 275 \r
 276 Copyright 2005 David Baird, All Rights Reserved.\r
 277 \r
 278 This text is free documentation; you can redistribute it and/or modify it\r
 279 under the same terms as the Perl documentation itself.\r
 280 \r
 281 =cut\r
 282 \r