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     BeerDB->setup("dbi:SQLite:t/beerdb.db");
  96     BeerDB->config->{uri_base} = "http://localhost/beerdb/";
  97     BeerDB->config->{rows_per_page} = 10;
  98     BeerDB->config->{display_tables} = [qw[beer brewery pub style]];
  99     BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
 100     BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
 101     BeerDB::Beer->untaint_columns(
 102         printable => [qw/abv name price notes/],
 103         integer => [qw/style brewery score/],
 104         date => [ qw/date/],
 105     );
 106
 107     use Class::DBI::Loader::Relationship;
 108     BeerDB->config->{loader}->relationship($_) for (
 109         "a brewery produces beers",
 110         "a style defines beers",
 111         "a pub has beers on handpumps");
 112     1;
 113
 114 This defines the C<BeerDB> application, which, as it inherits from
 115 C<Apache::MVC>, will be a mod_perl handler. This means we need to
 116 tell the Apache configuration about it:
 117
 118     <Location /beerdb>
 119         SetHandler perl-script
 120         PerlHandler BeerDB
 121     </Location>
 122
 123 And now we need some templates. As we'll see in the chapter on views,
 124 L<View.pod>, there are several types of template. We're going to copy
 125 the whole lot from the F<templates/> directory of the Maypole source
 126 package into the F</beerdb> directory under our web root.
 127
 128 And that's it. We should now be able to go to C<http://localhost/beerdb/>
 129 and see a menu of things to browse; C<http://localhost/beerdb/beer/list>
 130 will give a list of beers. There might not be any yet. There's a box
 131 that lets you add them.
 132
 133 If you have any problems getting to this point, you might want to look
 134 at L<http://wiki.simon-cozens.org/index.cgi?InstallationIssues>.
 135
 136 Play about with the site. Add some beers. Maybe go out and buy some beers
 137 to review if you need some inspiration. Don't be ill on my carpet.
 138
 139 =head2 Phases of a Maypole request
 140
 141 Now you should have a feel for what Maypole can do. The important thing
 142 to know at this point is that this is by no means B<all> that Maypole
 143 can do. What you've seen in the beer database example is all that Maypole
 144 can do if you don't customize it at all.
 145
 146 Remember that, for instance, we don't ever tell Maypole what tables our
 147 database has, or what columns each table has. We don't tell Maypole what
 148 those tables should be called or how to display them. We don't tell Maypole
 149 what to do - that we want to list, search, edit and delete beers and breweries.
 150 Maypole just works that out for itself. We can customize it and have Maypole
 151 do all sorts of interesting things with our database, and most of the rest
 152 of this manual will be about how to do that.
 153
 154 In order to do that, we need to look at what Maypole's actually doing.
 155
 156 XXX
 157
 158 =head2 The model class
 159
 160 =head2 The view class