1Maypole::Manual::About(U3s)er Contributed Perl DocumentatMiaoynpole::Manual::About(3)
2
3
4

NAME

6       Maypole::Manual::About - Introduction to Maypole
7

DESCRIPTION

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