doc/About.pod

   1
   2 =head1 Introduction to the Maypole Request Model
   3
   4 =head2 What is MVC for web applications?
   5
   6 =head2 What is Maypole?
   7
   8 =head2 The Beer Database example
   9
  10 Throughout this manual, we're going to be referring back to a particular
  11 application so that we can give concrete examples for the concepts we're
  12 talking about. We could say "C<related_accessors> returns a list of
  13 accessors which can be called to return a list of objects in a has-a
  14 relationship to the original", or we could say "if we call
  15 C<related_accessors> on while viewing C<brewery>, it returns C<beers>,
  16 because we can call C<beers> on a C<brewery> object to get a list of
  17 that berwery's beers."
  18
  19 Because Maypole is all about beer. If you look carefully, you can
  20 probably see men playing cricket on the village green. The first
  21 ever Maypole application was written to help me keep track of the many
  22 different ales available in my area - their styles, their tastes, their
  23 breweries, prices and so on. Then the more I thought about it, the more
  24 I thought it was a particularly good data model for demonstrating
  25 different kinds of database relationships.
  26
  27 We have a C<brewery> table, which has several C<beer>s. We'll call this
  28 a has-many relationship. The beers each have a C<style>; styles are
  29 stored in a separate table, so C<beer> has-a C<style>. Beers are in
  30 several pubs and a pub has several beers, so beers and pubs are in a
  31 many-to-many relationship. We use a link table called C<handpump> to
  32 relate pubs to beers.
  33
  34 All in all, this gives us a schema like the following:
  35
  36     create table brewery (
  37         id int not null auto_increment primary key,
  38         name varchar(30),
  39         url varchar(50),
  40         notes text
  41     );
  42
  43     create table beer (
  44         id int not null auto_increment primary key,
  45         brewery integer,
  46         style integer,
  47         name varchar(30),
  48         url varchar(120),
  49         score integer(2),
  50         price varchar(12),
  51         abv varchar(10),
  52         notes text
  53     );
  54
  55     create table handpump (
  56         id int not null auto_increment primary key,
  57         beer integer,
  58         pub integer
  59     );
  60
  61     create table pub (
  62         id int not null auto_increment primary key,
  63         name varchar(60),
  64         url varchar(120),
  65         notes text
  66     );
  67
  68     create table style (
  69         id int not null auto_increment primary key,
  70         name varchar(60),
  71         notes text
  72     );
  73
  74 If you have C<DBD::SQLite> available, then a database like this will
  75 be created when Maypole was installed. Let's now see how to set it up
  76 with a web interface.
  77
  78 =head2 Setting up Maypole
  79
  80 The first thing we need for a Maypole interface to a database is to
  81 have a database. If you don't have one, now would be a good time to
  82 create one, using the schema above.
  83
  84 The next thing we need is a module which is going to do all the work.
  85 Thankfully, it doesn't need to do B<all> the work itself. It's going to be a
  86 subclass of C<Maypole> or a Maypole front-end like C<Apache::MVC>.
  87
  88 Here's the driver class for our beer database application. We're not
  89 going to go into much detail about it here; we'll do that in L<Beer.pod>.
  90 For now, simply admire its brevity, as you realise this is all the code
  91 you need to write for a simple database front-end:
  92
  93     package BeerDB;
  94     use base 'Apache::MVC';
  95     use Class::DBI::Loader::Relationship;
  96     BeerDB->set_database("dbi:SQLite:t/beerdb.db");
  97     BeerDB->config->{uri_base} = "http://localhost/beerdb/";
  98     BeerDB->config->{rows_per_page} = 10;
  99     BeerDB->config->{display_tables} = [qw[beer brewery pub style]];
 100     BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
 101     BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
 102     BeerDB::Beer->untaint_columns(
 103         printable => [qw/abv name price notes/],
 104         integer => [qw/style brewery score/],
 105         date => [ qw/date/],
 106     );
 107     BeerDB->config->{loader}->relationship($_) for (
 108         "a brewery produces beers",
 109         "a style defines beers",
 110         "a pub has beers on handpumps");
 111     1;
 112
 113 This defines the C<BeerDB> application, which, as it inherits from
 114 C<Apache::MVC>, will be a mod_perl handler. This means we need to
 115 tell the Apache configuration about it:
 116
 117     <Location /beerdb>
 118         SetHandler perl-script
 119         PerlHandler BeerDB
 120     </Location>
 121
 122 And now we need some templates. As we'll see in the chapter on views,
 123 L<View.pod>, there are several types of template. We're going to copy
 124 the whole lot from the F<templates/> directory of the Maypole source
 125 package into the F</beerdb> directory under our web root.
 126
 127 And that's it. We should now be able to go to C<http://localhost/beerdb/>
 128 and see a menu of things to browse; C<http://localhost/beerdb/beer/list>
 129 will give a list of beers. There might not be any yet. There's a box
 130 that lets you add them.
 131
 132 If you have any problems getting to this point, you might want to look
 133 at L<http://wiki.simon-cozens.org/index.cgi?InstallationIssues>.
 134
 135 Play about with the site. Add some beers. Maybe go out and buy some beers
 136 to review if you need some inspiration. Don't be ill on my carpet.
 137
 138 =head2 Phases of a Maypole request
 139
 140 Now you should have a feel for what Maypole can do. The important thing
 141 to know at this point is that this is by no means B<all> that Maypole
 142 can do. What you've seen in the beer database example is all that Maypole
 143 can do if you don't customize it at all.
 144
 145 Remember that, for instance, we don't ever tell Maypole what tables our
 146 database has, or what columns each table has. We don't tell Maypole what
 147 those tables should be called or how to display them. We don't tell Maypole
 148 what to do - that we want to list, search, edit and delete beers and breweries.
 149 Maypole just works that out for itself. We can customize it and have Maypole
 150 do all sorts of interesting things with our database, and most of the rest
 151 of this manual will be about how to do that.
 152
 153 In order to do that, we need to look at what Maypole's actually doing.
 154
 155 XXX
 156
 157 =head2 The model class
 158
 159 =head2 The view class