X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2FAbout.pod;h=074f4bc1a223810e197a26c4a5447b7c5ba4b4ed;hb=43d50fc6cf12e98c44f485eea46ac35637dcce06;hp=b5cf3e7a2774f89ffb36875eef06f2ba0ae9c032;hpb=673e706b0cda16b4dea71d8fe7c430e4e29d78ac;p=maypole.git diff --git a/doc/About.pod b/doc/About.pod index b5cf3e7..074f4bc 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,7 +257,7 @@ 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 +As mentioned, Maypole is XXX =head2 The model class