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