-=head1 Introduction to the Maypole Request Model
+=head1 NAME
+
+Maypole::Manual::About - Introduction to Maypole
+
+=head1 DESCRIPTION
This chapter serves as a gentle introduction to Maypole and setting up
-Maypole applications. We look at Maypole is, how to get it up and
+Maypole applications. We look at what Maypole is, how to get it up and
running, and how to start thinking about building Maypole applications.
=head2 What is Maypole?
the user, and a Controller class which controls the other classes in
response to events triggered by the user. This analogy doesn't
correspond precisely to a web-based application, but we can take an
-important principle from it. As Andy Wardley explains:
+important principle from it. As Template Toolkit author Andy Wardley explains:
What the MVC-for-the-web crowd are really trying to achieve is a clear
separation of concerns. Put your database code in one place, your
you develop so rapidly: because most of the time, you don't need to do
any development at all.
-=head2 Installing Maypole
-
-The first thing you're going to need to do to get Maypole running is to
-install it. Maypole needs an absolute shedload of Perl modules from CPAN
-to do its job. I am unrepentant about this. Maypole does a lot of work,
-so that you don't have to. This is called code re-use, and if we're
-serious about code re-use, then Maypole should be re-using as much code
-as possible in terms of Perl modules. In another sense, this gives the
-impression that Maypole doesn't actually do all that much itself,
-because all it's doing is gluing together already-existing code. Well,
-welcome to code re-use.
-
-The downside of code re-use is, of course, that you then have to install
-a shedload of Perl modules from CPAN. If you're using OpenBSD or
-FreeBSD, the wonderful ports system will be your friend. There's a
-Maypole port in C<p5-Maypole>. Just type C<make install>.
-
-Debian users, hang in there. There's a package coming.
-
-For other Unices, the L<CPANPLUS> or C<CPAN> modules will help with
-this. If you don't have C<CPANPLUS> installed, my recommendation is to
-use C<perl -MCPAN -e install CPANPLUS> to install it and then throw
-C<CPAN.pm> away. In any case, one of these two should get all that
-Maypole needs:
-
- % perl -MCPANPLUS -e 'install Maypole'
- % perl -MCPAN -e 'install Maypole'
-
-I don't know if Maypole works on Windows. I'm not sure I care.
-
-You're also going to need a database server and a web server. For
-databases, I recommend SQLite (if you install the C<DBD::SQLite> module,
-you get the SQLite library for free) for prototyping and mysql for
-production; heavier duty users should use Postgresql or Oracle - Maypole
-should be happy with them all. Maypole is happiest when running under
-Apache C<mod_perl>, with the C<Apache::Request> module installed, but as
-I said, it is a blank slate, and everything is customizable. There is a
-C<CGI::Maypole> frontend available to run as a standalone CGI script.
=head2 The Beer Database example
talking about. We could say "C<related_accessors> returns a list of
accessors which can be called to return a list of objects in a has-a
relationship to the original", or we could say "if we call
-C<related_accessors> on while viewing C<brewery>, it returns C<beers>,
+C<related_accessors> while viewing a C<brewery>, it returns C<beers>,
because we can call C<beers> on a C<brewery> object to get a list of
-that berwery's beers."
+that brewery's beers."
Because Maypole is all about beer. If you look carefully, you can
probably see men playing cricket on the village green. The first
The first thing we need for a Maypole interface to a database is to
have a database. If you don't have one, now would be a good time to
-create one, using the schema above.
+create one, using the schema above. If you're creating a database
+by hand, don't forget to grant permissions for your Apache server to
+access it as well as yourself (typically a user name like C<www-data>
+or C<wwwrun>).
The next thing we need is a module which is going to do all the work.
Thankfully, it doesn't need to do B<all> the work itself. It's going to be a
subclass of C<Maypole> or a Maypole front-end like C<Apache::MVC>.
+It roughly corresponds to the controller in an MVC design, and is
+also referred to as the driver, handler or request.
Here's the driver class for our beer database application. We're not
-going to go into much detail about it here; we'll do that in L<Beer.pod>.
+going to go into much detail about it here; we'll do that in the
+L<Beer Database|Maypole::Manual::Beer> chapter.
For now, simply admire its brevity, as you realise this is all the code
you need to write for a simple database front-end:
package BeerDB;
- use base 'Apache::MVC';
+ use Maypole::Application;
BeerDB->setup("dbi:SQLite:t/beerdb.db");
- BeerDB->config->{uri_base} = "http://localhost/beerdb/";
- BeerDB->config->{rows_per_page} = 10;
- BeerDB->config->{display_tables} = [qw[beer brewery pub style]];
+ BeerDB->config->uri_base("http://localhost/beerdb");
+ BeerDB->config->template_root("/path/to/templates");
+ BeerDB->config->rows_per_page(10);
+ BeerDB->config->display_tables([qw[beer brewery pub style]]);
BeerDB::Brewery->untaint_columns( printable => [qw/name notes url/] );
BeerDB::Style->untaint_columns( printable => [qw/name notes/] );
BeerDB::Beer->untaint_columns(
"a pub has beers on handpumps");
1;
-This defines the C<BeerDB> application, which, as it inherits from
-C<Apache::MVC>, will be a mod_perl handler. This means we need to
-tell the Apache configuration about it:
+There's a version of this program in the F<ex/> directory in the Maypole
+files that you downloaded in the F<~root/.cpan/> build area.
+This defines the C<BeerDB> application.
+To set it up as a mod_perl handler, just tell the Apache configuration
+about it:
<Location /beerdb>
SetHandler perl-script
PerlHandler BeerDB
</Location>
-And now we need some templates. As we'll see in the chapter on views,
-L<View.pod>, there are several types of template. We're going to copy
+To use it as a CGI script, put it in your F<cgi-bin> directory,
+together with a small file called F<beer.cgi>:
+
+ #!/usr/bin/perl
+ use strict;
+ use warnings;
+ use BeerDB;
+ BeerDB->run();
+
+and change one line in C<BeerDB.pm>:
+
+ BeerDB->config->uri_base("http://localhost/cgi-bin/beer.cgi");
+
+And now we need some templates. As we'll see in the chapter on
+L<views|Maypole::Manual::View>, there are several types of template.
+We're going to copy
the whole lot from the F<templates/> directory of the Maypole source
package into the F</beerdb> directory under our web root.
+Make the C<template_root> in C<BeerDB> agree with your path.
And that's it. We should now be able to go to C<http://localhost/beerdb/>
+or C<http://localhost/cgi-bin/beer.cgi/>
and see a menu of things to browse; C<http://localhost/beerdb/beer/list>
will give a list of beers. There might not be any yet. There's a box
that lets you add them.
-If you have any problems getting to this point, you might want to look
-at L<http://wiki.simon-cozens.org/index.cgi?InstallationIssues>.
+If you have any problems getting to this point, you might want to look at
+L<http://maypole.perl.org>. There's a FAQ and a link to a mailing
+list.
Play about with the site. Add some beers. Maybe go out and buy some beers
to review if you need some inspiration. Don't be ill on my carpet.
of this manual will be about how to do that.
In order to do that, we need to look at what Maypole's actually doing.
+Here's a quick overview, there's more detail in the
+L<Workflow|Maypole::Manual::Workflow> chapter.
As mentioned, Maypole is responsible for turning a URL into an object, a
-method call, and some templated output. Here's a handy diagram to
-explain how it does that:
+method call, and some templated output.
+
+=for html
+Here's a handy diagram to explain how it does that:
=for html
<IMG SRC="maypole_process2.png">
as a parameter, and passes the whole lot to the view class for templating.
In the next two chapters, we'll look at how Maypole's default model and
view classes generally do what you want them to do.
+
+=head2 Links
+
+L<Contents|Maypole::Manual>,
+Next L<Maypole Model Classes|Maypole::Manual::Model>
projects / maypole.git / blobdiff