X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2FAbout.pod;h=3600a9476dcc01e3db038fd04ebff6fc3ea2c1dd;hb=85968ef28d078868c8e2865a3e76f81ddd4ec94c;hp=b5cf3e7a2774f89ffb36875eef06f2ba0ae9c032;hpb=2c2a72adcc01c1260b410103fa6bab06623f04be;p=maypole.git diff --git a/doc/About.pod b/doc/About.pod index b5cf3e7..3600a94 100644 --- a/doc/About.pod +++ b/doc/About.pod @@ -1,10 +1,114 @@ =head1 Introduction to the Maypole Request Model -=head2 What is MVC for web applications? +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 +running, and how to start thinking about building Maypole applications. =head2 What is Maypole? +Presumably you have some idea of what Maypole is all about, or otherwise +you wouldn't be reading this manual. But Maypole is good at many +different things, and you may have accidentally focussed on one aspect +of Maypole while missing the big picture. + +For instance, you may know that Maypole is extremely good at putting web +front-ends onto databases. This is true, but it's only a part of what +Maypole does. You may have heard that Maypole is a web application +framework, which is true, but it doesn't mean very much. There are a +huge number of things that Maypole can do, because it's very much a +blank slate. You can make it do what you will. In this manual, we'll be +making it act as a front-end to a database, as a social network site, as +an intranet portal, and many other things besides. It is a framework. + +I like to think that Maypole is a way of going from a URL to a method +call to some output. If you have a URL like C, +Maypole is a way of having it load up product number 12, call an +C method, and produce a page about what it's just done. The +reason Maypole is such a big deal is because it does all this for you. +You no longer have to care about your web server. You hardly have to +care about your database. You don't have to care about templating +modules, parsing CGI parameters, or anything else. You only need to care +about business logic, and the business logic in this instance is how you +C a product, and what you need to display about it once you've +done so. This is what programming should be: only caring about the work +that distinguishes one program from another. + +It does this using a technique called MVC for web applications. + +=head2 What is MVC for web applications? + +Maypole was originally called C, reflecting its basis in +the Model-View-Controller design pattern. (I had to change it firstly +because Maypole isn't tied to Apache, and secondly because +C is a really dull name.) It's the same design pattern that +forms the foundation of similar projects in other languages, such as +Java's Struts framework. + +This design pattern is found primarily in graphical applications; the +idea is that you have a Model class which represents and manipulates +your data, a View class which is responsible for displaying that data to +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: + + 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 + application code in another, your presentation code in a third place. + That way, you can chop and change different elements at will, + hopefully without affecting the other parts (depending on how well your + concerns are separated, of course). This is common sense and good practice. + MVC achieves this separation of concerns as a by-product of clearly + separating inputs (controls) and outputs (views). + +This is what Maypole does. It has a number of database drivers, a number +of front-end drivers and a number of templating presentation drivers. +In common cases, Maypole provides precisely what you need for all of +these areas, and you get to concentrate on writing just the business +logic of your application. This is one of the reasons why Maypole lets +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. Just type C. + +Debian users, hang in there. There's a package coming. + +For other Unices, the L or C modules will help with +this. If you don't have C installed, my recommendation is to +use C to install it and then throw +C 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 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, with the C module installed, but as +I said, it is a blank slate, and everything is customizable. There is a +C frontend available to run as a standalone CGI script. + =head2 The Beer Database example Throughout this manual, we're going to be referring back to a particular @@ -153,8 +257,56 @@ 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. -XXX - -=head2 The model class - -=head2 The view class +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: + +=for html + + +Maypole's process revolves around the concept of the Maypole request +object. This is a little like Apache's request object, but at a much +higher level - in fact, in C-based Maypole front-ends, the +Apache request object is incorporated in the Maypole request object. All +that Maypole does is gradually flesh out this object until it contains +something in the C member, and then it is dispatched back to the +front-end for output. + +So to start with, we take the Apache request (or CGI object, or other +way of isolating what's going on) and break it down. For instance, we +turn the URL C into + + { + table => "beer", + action => "view", + args => [ 1 ] + } + +Then Maypole will check that C is a real table, and find the class +that models it. It also checks whether or not we're allowed to call the +C method over the network: + + { + table => "beer", + action => "view", + args => [ 1 ], + model_class => "BeerDB::Beer" + } + +Then there's a user-defined authentication method, which by default just +lets us do anything. Now we hand over to the model class, which loads up +the object, and decides what template we want to use: + + { + table => "beer", + action => "view", + args => [ ], + objects => [ BeerDB::Beer->retrieve(1) ], + model_class => "BeerDB::Beer", + template => "view" + } + +Then it calls Cview>, passing in the request object +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.