1Maypole::Manual::About(U3s)er Contributed Perl DocumentatMiaoynpole::Manual::About(3)
2
6 Maypole::Manual::About - Introduction to Maypole
7
9 This chapter serves as a gentle introduction to Maypole and setting up
10 Maypole applications. We look at what Maypole is, how to get it up and
11 running, and how to start thinking about building Maypole applications.
12 What is Maypole?
14 Presumably you have some idea of what Maypole is all about, or other‐
16 wise you wouldn't be reading this manual. But Maypole is good at many
17 different things, and you may have accidentally focussed on one aspect
18 of Maypole while missing the big picture.
19 For instance, you may know that Maypole is extremely good at putting
21 web front-ends onto databases. This is true, but it's only a part of
22 what Maypole does. You may have heard that Maypole is a web application
23 framework, which is true, but it doesn't mean very much. There are a
24 huge number of things that Maypole can do, because it's very much a
25 blank slate. You can make it do what you will. In this manual, we'll be
26 making it act as a front-end to a database, as a social network site,
27 as an intranet portal, and many other things besides. It is a frame‐
28 work.
29 I like to think that Maypole is a way of going from a URL to a method
31 call to some output. If you have a URL like "/product/order/12", May‐
32 pole is a way of having it load up product number 12, call an "order"
33 method, and produce a page about what it's just done. The reason May‐
34 pole is such a big deal is because it does all this for you. You no
35 longer have to care about your web server. You hardly have to care
36 about your database. You don't have to care about templating modules,
37 parsing CGI parameters, or anything else. You only need to care about
38 business logic, and the business logic in this instance is how you
39 "order" a product, and what you need to display about it once you've
40 done so. This is what programming should be: only caring about the work
41 that distinguishes one program from another.
42 It does this using a technique called MVC for web applications.
44 What is MVC for web applications?
46 Maypole was originally called "Apache::MVC", reflecting its basis in
48 the Model-View-Controller design pattern. (I had to change it firstly
49 because Maypole isn't tied to Apache, and secondly because
50 "Apache::MVC" is a really dull name.) It's the same design pattern that
51 forms the foundation of similar projects in other languages, such as
52 Java's Struts framework.
53 This design pattern is found primarily in graphical applications; the
55 idea is that you have a Model class which represents and manipulates
56 your data, a View class which is responsible for displaying that data
57 to the user, and a Controller class which controls the other classes in
58 response to events triggered by the user. This analogy doesn't corre‐
59 spond precisely to a web-based application, but we can take an impor‐
60 tant principle from it. As Template Toolkit author Andy Wardley
61 explains:
62 What the MVC-for-the-web crowd are really trying to achieve is a clear
64 separation of concerns. Put your database code in one place, your
65 application code in another, your presentation code in a third place.
66 That way, you can chop and change different elements at will,
67 hopefully without affecting the other parts (depending on how well your
68 concerns are separated, of course). This is common sense and good practice.
69 MVC achieves this separation of concerns as a by-product of clearly
70 separating inputs (controls) and outputs (views).
71 This is what Maypole does. It has a number of database drivers, a num‐
73 ber of front-end drivers and a number of templating presentation driv‐
74 ers. In common cases, Maypole provides precisely what you need for all
75 of these areas, and you get to concentrate on writing just the business
76 logic of your application. This is one of the reasons why Maypole lets
77 you develop so rapidly: because most of the time, you don't need to do
78 any development at all.
79 The Beer Database example
81 Throughout this manual, we're going to be referring back to a particu‐
83 lar application so that we can give concrete examples for the concepts
84 we're talking about. We could say ""related_accessors" returns a list
85 of accessors which can be called to return a list of objects in a has-a
86 relationship to the original", or we could say "if we call
87 "related_accessors" while viewing a "brewery", it returns "beers",
88 because we can call "beers" on a "brewery" object to get a list of that
89 brewery's beers."
90 Because Maypole is all about beer. If you look carefully, you can prob‐
92 ably see men playing cricket on the village green. The first ever May‐
93 pole application was written to help me keep track of the many differ‐
94 ent ales available in my area - their styles, their tastes, their brew‐
95 eries, prices and so on. Then the more I thought about it, the more I
96 thought it was a particularly good data model for demonstrating differ‐
97 ent kinds of database relationships.
98 We have a "brewery" table, which has several "beer"s. We'll call this a
100 has-many relationship. The beers each have a "style"; styles are stored
101 in a separate table, so "beer" has-a "style". Beers are in several pubs
102 and a pub has several beers, so beers and pubs are in a many-to-many
103 relationship. We use a link table called "handpump" to relate pubs to
104 beers.
105 All in all, this gives us a schema like the following:
107 create table brewery (
109 id int not null auto_increment primary key,
110 name varchar(30),
111 url varchar(50),
112 notes text
113 );
114 create table beer (
116 id int not null auto_increment primary key,
117 brewery integer,
118 style integer,
119 name varchar(30),
120 url varchar(120),
121 score integer(2),
122 price varchar(12),
123 abv varchar(10),
124 notes text
125 );
126 create table handpump (
128 id int not null auto_increment primary key,
129 beer integer,
130 pub integer
131 );
132 create table pub (
134 id int not null auto_increment primary key,
135 name varchar(60),
136 url varchar(120),
137 notes text
138 );
139 create table style (
141 id int not null auto_increment primary key,
142 name varchar(60),
143 notes text
144 );
145 If you have "DBD::SQLite" available, then a database like this will be
147 created when Maypole was installed. Let's now see how to set it up with
148 a web interface.
149 Setting up Maypole
151 The first thing we need for a Maypole interface to a database is to
153 have a database. If you don't have one, now would be a good time to
154 create one, using the schema above. If you're creating a database by
155 hand, don't forget to grant permissions for your Apache server to
156 access it as well as yourself (typically a user name like "www-data" or
157 "wwwrun").
158 The next thing we need is a module which is going to do all the work.
160 Thankfully, it doesn't need to do all the work itself. It's going to be
161 a subclass of "Maypole" or a Maypole front-end like "Apache::MVC". It
162 roughly corresponds to the controller in an MVC design, and is also
163 referred to as the driver, handler or request.
164 Here's the driver class for our beer database application. We're not
166 going to go into much detail about it here; we'll do that in the Beer
167 Database chapter. For now, simply admire its brevity, as you realise
168 this is all the code you need to write for a simple database front-end:
169 package BeerDB;
171 use Maypole::Application;
172 BeerDB->setup("dbi:SQLite:t/beerdb.db");
173 BeerDB->config->uri_base("http://localhost/beerdb");
174 BeerDB->config->template_root("/path/to/templates");
175 BeerDB->config->rows_per_page(10);
176 BeerDB->config->display_tables([qw[beer brewery pub style]]);
177 BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
178 BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
179 BeerDB::Beer->untaint_columns(
180 printable => [qw/abv name price notes/],
181 integer => [qw/style brewery score/],
182 date => [ qw/date/],
183 );
184 use Class::DBI::Loader::Relationship;
186 BeerDB->config->{loader}->relationship($_) for (
187 "a brewery produces beers",
188 "a style defines beers",
189 "a pub has beers on handpumps");
190 1;
191 There's a version of this program in the ex/ directory in the Maypole
193 files that you downloaded in the ~root/.cpan/ build area. This defines
194 the "BeerDB" application. To set it up as a mod_perl handler, just
195 tell the Apache configuration about it:
196 <Location /beerdb>
198 SetHandler perl-script
199 PerlHandler BeerDB
200 </Location>
201 To use it as a CGI script, put it in your cgi-bin directory, together
203 with a small file called beer.cgi:
204 #!/usr/bin/perl
206 use strict;
207 use warnings;
208 use BeerDB;
209 BeerDB->run();
210 and change one line in "BeerDB.pm":
212 BeerDB->config->uri_base("http://localhost/cgi-bin/beer.cgi");
214 And now we need some templates. As we'll see in the chapter on views,
216 there are several types of template. We're going to copy the whole lot
217 from the templates/ directory of the Maypole source package into the
218 /beerdb directory under our web root. Make the "template_root" in
219 "BeerDB" agree with your path.
220 And that's it. We should now be able to go to "http://local‐
222 host/beerdb/" or "http://localhost/cgi-bin/beer.cgi/" and see a menu of
223 things to browse; "http://localhost/beerdb/beer/list" will give a list
224 of beers. There might not be any yet. There's a box that lets you add
225 them.
226 If you have any problems getting to this point, you might want to look
228 at <http://maypole.perl.org>. There's a FAQ and a link to a mailing
229 list.
230 Play about with the site. Add some beers. Maybe go out and buy some
232 beers to review if you need some inspiration. Don't be ill on my car‐
233 pet.
234 Phases of a Maypole request
236 Now you should have a feel for what Maypole can do. The important thing
238 to know at this point is that this is by no means all that Maypole can
239 do. What you've seen in the beer database example is all that Maypole
240 can do if you don't customize it at all.
241 Remember that, for instance, we don't ever tell Maypole what tables our
243 database has, or what columns each table has. We don't tell Maypole
244 what those tables should be called or how to display them. We don't
245 tell Maypole what to do - that we want to list, search, edit and delete
246 beers and breweries. Maypole just works that out for itself. We can
247 customize it and have Maypole do all sorts of interesting things with
248 our database, and most of the rest of this manual will be about how to
249 do that.
250 In order to do that, we need to look at what Maypole's actually doing.
252 Here's a quick overview, there's more detail in the Workflow chapter.
253 As mentioned, Maypole is responsible for turning a URL into an object,
255 a method call, and some templated output.
256 Maypole's process revolves around the concept of the Maypole request
258 object. This is a little like Apache's request object, but at a much
259 higher level - in fact, in "mod_perl"-based Maypole front-ends, the
260 Apache request object is incorporated in the Maypole request object.
261 All that Maypole does is gradually flesh out this object until it con‐
262 tains something in the "output" member, and then it is dispatched back
263 to the front-end for output.
264 So to start with, we take the Apache request (or CGI object, or other
266 way of isolating what's going on) and break it down. For instance, we
267 turn the URL "/beer/view/1" into
268 {
270 table => "beer",
271 action => "view",
272 args => [ 1 ]
273 }
274 Then Maypole will check that "beer" is a real table, and find the class
276 that models it. It also checks whether or not we're allowed to call the
277 "view" method over the network:
278 {
280 table => "beer",
281 action => "view",
282 args => [ 1 ],
283 model_class => "BeerDB::Beer"
284 }
285 Then there's a user-defined authentication method, which by default
287 just lets us do anything. Now we hand over to the model class, which
288 loads up the object, and decides what template we want to use:
289 {
291 table => "beer",
292 action => "view",
293 args => [ ],
294 objects => [ BeerDB::Beer->retrieve(1) ],
295 model_class => "BeerDB::Beer",
296 template => "view"
297 }
298 Then it calls "BeerDB::Beer->view", passing in the request object as a
300 parameter, and passes the whole lot to the view class for templating.
301 In the next two chapters, we'll look at how Maypole's default model and
302 view classes generally do what you want them to do.
303 Links
305 Contents, Next Maypole Model Classes
307perl v5.8.8 2005-11-23 Maypole::Manual::About(3)