2 =head1 Introduction to the Maypole Request Model
4 =head2 What is MVC for web applications?
6 =head2 What is Maypole?
8 =head2 The Beer Database example
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."
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.
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
34 All in all, this gives us a schema like the following:
36 create table brewery (
37 id int not null auto_increment primary key,
44 id int not null auto_increment primary key,
55 create table handpump (
56 id int not null auto_increment primary key,
62 id int not null auto_increment primary key,
69 id int not null auto_increment primary key,
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
78 =head2 Setting up Maypole
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.
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>.
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:
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/],
107 BeerDB->config->{loader}->relationship($_) for (
108 "a brewery produces beers",
109 "a style defines beers",
110 "a pub has beers on handpumps");
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:
118 SetHandler perl-script
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.
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.
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>.
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.
138 =head2 Phases of a Maypole request
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.
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.
153 In order to do that, we need to look at what Maypole's actually doing.
157 =head2 The model class
159 =head2 The view class