From: Sebastian Riedel Date: Sun, 26 Sep 2004 20:58:52 +0000 (+0000) Subject: Moved doc/*.pod to lib/Maypole/Manual/ and added new Maypole.pm X-Git-Tag: 2.10~156 X-Git-Url: https://git.decadent.org.uk/gitweb/?a=commitdiff_plain;h=616082000cbe7305fbfc84d33bb2f9d53cc86f3c;p=maypole.git Moved doc/*.pod to lib/Maypole/Manual/ and added new Maypole.pm documentation git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@206 48953598-375a-da11-a14b-00016c27c3ee --- diff --git a/Changes b/Changes index 4575ddc..f017a09 100644 --- a/Changes +++ b/Changes @@ -1,7 +1,7 @@ Revision history for Perl extension Maypole 2.0 XXX XXX XX XX:XX:XX XXX XXXX - - Added parse_args() (Simon Flack) + - added parse_args() (Simon Flack) - call additional_data() and authenticate() for plain templates - merged Apache2::MVC (mod_perl2 support) into Apache::MVC - added Maypole::Application universal front-end @@ -9,14 +9,16 @@ Revision history for Perl extension Maypole - $r->{query} is now deprecated, use $r->{params} for GET and POST - fixed multiple value handling (Simon Flack) - added exception handling (Simon Flack) - - Fixed documentation bugs - - Changed default documentencoding to utf8. Change with + - fixed documentation bugs + - changed default documentencoding to utf8. Change with $r->config->{document_encoding} - - Removed Maypole::View::Mason as it's distributed separately on CPAN. - - Factory templates are now XHTML 1.1 compliant. + - removed Maypole::View::Mason as it's distributed separately on CPAN. + - factory templates are now XHTML 1.1 compliant. - made the config hash into -> Maypole::Config - accessors for everything - - Win32 support + - win32 support + - new documentation for Maypole.pm (Simon Flack) + - moved doc/*.pod to lib/Maypole/Manual 1.7 Sat Jul 17 20:15:26 BST 2004 - Emergency release - we lost the "use Maypole::Constants" from diff --git a/doc/About.pod b/doc/About.pod deleted file mode 100644 index 3600a94..0000000 --- a/doc/About.pod +++ /dev/null @@ -1,312 +0,0 @@ - -=head1 Introduction to the Maypole Request Model - -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 -application so that we can give concrete examples for the concepts we're -talking about. We could say "C 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 on while viewing C, it returns C, -because we can call C on a C object to get a list of -that berwery'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 -ever Maypole application was written to help me keep track of the many -different ales available in my area - their styles, their tastes, their -breweries, prices and so on. Then the more I thought about it, the more -I thought it was a particularly good data model for demonstrating -different kinds of database relationships. - -We have a C table, which has several Cs. We'll call this -a has-many relationship. The beers each have a C