2 =head1 Introduction to the Maypole Request Model
4 This chapter serves as a gentle introduction to Maypole and setting up
5 Maypole applications. We look at Maypole is, how to get it up and
6 running, and how to start thinking about building Maypole applications.
8 =head2 What is Maypole?
10 Presumably you have some idea of what Maypole is all about, or otherwise
11 you wouldn't be reading this manual. But Maypole is good at many
12 different things, and you may have accidentally focussed on one aspect
13 of Maypole while missing the big picture.
15 For instance, you may know that Maypole is extremely good at putting web
16 front-ends onto databases. This is true, but it's only a part of what
17 Maypole does. You may have heard that Maypole is a web application
18 framework, which is true, but it doesn't mean very much. There are a
19 huge number of things that Maypole can do, because it's very much a
20 blank slate. You can make it do what you will. In this manual, we'll be
21 making it act as a front-end to a database, as a social network site, as
22 an intranet portal, and many other things besides. It is a framework.
24 I like to think that Maypole is a way of going from a URL to a method
25 call to some output. If you have a URL like C</product/order/12>,
26 Maypole is a way of having it load up product number 12, call an
27 C<order> method, and produce a page about what it's just done. The
28 reason Maypole is such a big deal is because it does all this for you.
29 You no longer have to care about your web server. You hardly have to
30 care about your database. You don't have to care about templating
31 modules, parsing CGI parameters, or anything else. You only need to care
32 about business logic, and the business logic in this instance is how you
33 C<order> a product, and what you need to display about it once you've
34 done so. This is what programming should be: only caring about the work
35 that distinguishes one program from another.
37 It does this using a technique called MVC for web applications.
39 =head2 What is MVC for web applications?
41 Maypole was originally called C<Apache::MVC>, reflecting its basis in
42 the Model-View-Controller design pattern. (I had to change it firstly
43 because Maypole isn't tied to Apache, and secondly because
44 C<Apache::MVC> is a really dull name.) It's the same design pattern that
45 forms the foundation of similar projects in other languages, such as
46 Java's Struts framework.
48 This design pattern is found primarily in graphical applications; the
49 idea is that you have a Model class which represents and manipulates
50 your data, a View class which is responsible for displaying that data to
51 the user, and a Controller class which controls the other classes in
52 response to events triggered by the user. This analogy doesn't
53 correspond precisely to a web-based application, but we can take an
54 important principle from it. As Andy Wardley explains:
56 What the MVC-for-the-web crowd are really trying to achieve is a clear
57 separation of concerns. Put your database code in one place, your
58 application code in another, your presentation code in a third place.
59 That way, you can chop and change different elements at will,
60 hopefully without affecting the other parts (depending on how well your
61 concerns are separated, of course). This is common sense and good practice.
62 MVC achieves this separation of concerns as a by-product of clearly
63 separating inputs (controls) and outputs (views).
65 This is what Maypole does. It has a number of database drivers, a number
66 of front-end drivers and a number of templating presentation drivers.
67 In common cases, Maypole provides precisely what you need for all of
68 these areas, and you get to concentrate on writing just the business
69 logic of your application. This is one of the reasons why Maypole lets
70 you develop so rapidly: because most of the time, you don't need to do
71 any development at all.
73 =head2 Installing Maypole
75 The first thing you're going to need to do to get Maypole running is to
76 install it. Maypole needs an absolute shedload of Perl modules from CPAN
77 to do its job. I am unrepentant about this. Maypole does a lot of work,
78 so that you don't have to. This is called code re-use, and if we're
79 serious about code re-use, then Maypole should be re-using as much code
80 as possible in terms of Perl modules. In another sense, this gives the
81 impression that Maypole doesn't actually do all that much itself,
82 because all it's doing is gluing together already-existing code. Well,
83 welcome to code re-use.
85 The downside of code re-use is, of course, that you then have to install
86 a shedload of Perl modules from CPAN. If you're using OpenBSD or
87 FreeBSD, the wonderful ports system will be your friend. There's a
88 Maypole port in C<p5-Maypole>. Just type C<make install>.
90 Debian users, hang in there. There's a package coming.
92 For other Unices, the L<CPANPLUS> or C<CPAN> modules will help with
93 this. If you don't have C<CPANPLUS> installed, my recommendation is to
94 use C<perl -MCPAN -e install CPANPLUS> to install it and then throw
95 C<CPAN.pm> away. In any case, one of these two should get all that
98 % perl -MCPANPLUS -e 'install Maypole'
99 % perl -MCPAN -e 'install Maypole'
101 I don't know if Maypole works on Windows. I'm not sure I care.
103 You're also going to need a database server and a web server. For
104 databases, I recommend SQLite (if you install the C<DBD::SQLite> module,
105 you get the SQLite library for free) for prototyping and mysql for
106 production; heavier duty users should use Postgresql or Oracle - Maypole
107 should be happy with them all. Maypole is happiest when running under
108 Apache C<mod_perl>, with the C<Apache::Request> module installed, but as
109 I said, it is a blank slate, and everything is customizable. There is a
110 C<CGI::Maypole> frontend available to run as a standalone CGI script.
112 =head2 The Beer Database example
114 Throughout this manual, we're going to be referring back to a particular
115 application so that we can give concrete examples for the concepts we're
116 talking about. We could say "C<related_accessors> returns a list of
117 accessors which can be called to return a list of objects in a has-a
118 relationship to the original", or we could say "if we call
119 C<related_accessors> on while viewing C<brewery>, it returns C<beers>,
120 because we can call C<beers> on a C<brewery> object to get a list of
121 that berwery's beers."
123 Because Maypole is all about beer. If you look carefully, you can
124 probably see men playing cricket on the village green. The first
125 ever Maypole application was written to help me keep track of the many
126 different ales available in my area - their styles, their tastes, their
127 breweries, prices and so on. Then the more I thought about it, the more
128 I thought it was a particularly good data model for demonstrating
129 different kinds of database relationships.
131 We have a C<brewery> table, which has several C<beer>s. We'll call this
132 a has-many relationship. The beers each have a C<style>; styles are
133 stored in a separate table, so C<beer> has-a C<style>. Beers are in
134 several pubs and a pub has several beers, so beers and pubs are in a
135 many-to-many relationship. We use a link table called C<handpump> to
136 relate pubs to beers.
138 All in all, this gives us a schema like the following:
140 create table brewery (
141 id int not null auto_increment primary key,
148 id int not null auto_increment primary key,
159 create table handpump (
160 id int not null auto_increment primary key,
166 id int not null auto_increment primary key,
173 id int not null auto_increment primary key,
178 If you have C<DBD::SQLite> available, then a database like this will
179 be created when Maypole was installed. Let's now see how to set it up
180 with a web interface.
182 =head2 Setting up Maypole
184 The first thing we need for a Maypole interface to a database is to
185 have a database. If you don't have one, now would be a good time to
186 create one, using the schema above.
188 The next thing we need is a module which is going to do all the work.
189 Thankfully, it doesn't need to do B<all> the work itself. It's going to be a
190 subclass of C<Maypole> or a Maypole front-end like C<Apache::MVC>.
192 Here's the driver class for our beer database application. We're not
193 going to go into much detail about it here; we'll do that in L<Beer.pod>.
194 For now, simply admire its brevity, as you realise this is all the code
195 you need to write for a simple database front-end:
198 use Maypole::Application;
199 BeerDB->setup("dbi:SQLite:t/beerdb.db");
200 BeerDB->config->{uri_base} = "http://localhost/beerdb";
201 BeerDB->config->{template_root} = "/path/to/templates";
202 BeerDB->config->{rows_per_page} = 10;
203 BeerDB->config->{display_tables} = [qw[beer brewery pub style]];
204 BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
205 BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
206 BeerDB::Beer->untaint_columns(
207 printable => [qw/abv name price notes/],
208 integer => [qw/style brewery score/],
212 use Class::DBI::Loader::Relationship;
213 BeerDB->config->{loader}->relationship($_) for (
214 "a brewery produces beers",
215 "a style defines beers",
216 "a pub has beers on handpumps");
219 This defines the C<BeerDB> application, which, as it inherits from
220 C<Apache::MVC>, will be a mod_perl handler. This means we need to
221 tell the Apache configuration about it:
224 SetHandler perl-script
228 And now we need some templates. As we'll see in the chapter on views,
229 L<View.pod>, there are several types of template. We're going to copy
230 the whole lot from the F<templates/> directory of the Maypole source
231 package into the F</beerdb> directory under our web root.
233 And that's it. We should now be able to go to C<http://localhost/beerdb/>
234 and see a menu of things to browse; C<http://localhost/beerdb/beer/list>
235 will give a list of beers. There might not be any yet. There's a box
236 that lets you add them.
238 If you have any problems getting to this point, you might want to look
239 at L<http://maypole.perl.org>.
241 Play about with the site. Add some beers. Maybe go out and buy some beers
242 to review if you need some inspiration. Don't be ill on my carpet.
244 =head2 Phases of a Maypole request
246 Now you should have a feel for what Maypole can do. The important thing
247 to know at this point is that this is by no means B<all> that Maypole
248 can do. What you've seen in the beer database example is all that Maypole
249 can do if you don't customize it at all.
251 Remember that, for instance, we don't ever tell Maypole what tables our
252 database has, or what columns each table has. We don't tell Maypole what
253 those tables should be called or how to display them. We don't tell Maypole
254 what to do - that we want to list, search, edit and delete beers and breweries.
255 Maypole just works that out for itself. We can customize it and have Maypole
256 do all sorts of interesting things with our database, and most of the rest
257 of this manual will be about how to do that.
259 In order to do that, we need to look at what Maypole's actually doing.
261 As mentioned, Maypole is responsible for turning a URL into an object, a
262 method call, and some templated output. Here's a handy diagram to
263 explain how it does that:
266 <IMG SRC="maypole_process2.png">
268 Maypole's process revolves around the concept of the Maypole request
269 object. This is a little like Apache's request object, but at a much
270 higher level - in fact, in C<mod_perl>-based Maypole front-ends, the
271 Apache request object is incorporated in the Maypole request object. All
272 that Maypole does is gradually flesh out this object until it contains
273 something in the C<output> member, and then it is dispatched back to the
274 front-end for output.
276 So to start with, we take the Apache request (or CGI object, or other
277 way of isolating what's going on) and break it down. For instance, we
278 turn the URL C</beer/view/1> into
286 Then Maypole will check that C<beer> is a real table, and find the class
287 that models it. It also checks whether or not we're allowed to call the
288 C<view> method over the network:
294 model_class => "BeerDB::Beer"
297 Then there's a user-defined authentication method, which by default just
298 lets us do anything. Now we hand over to the model class, which loads up
299 the object, and decides what template we want to use:
305 objects => [ BeerDB::Beer->retrieve(1) ],
306 model_class => "BeerDB::Beer",
310 Then it calls C<BeerDB::Beer-E<gt>view>, passing in the request object
311 as a parameter, and passes the whole lot to the view class for templating.
312 In the next two chapters, we'll look at how Maypole's default model and
313 view classes generally do what you want them to do.