POD updates: fleshed out some weak areas, reorganised a little and fixed some typogra...

[maypole.git] / lib / Maypole.pm

diff --git a/lib/Maypole.pm b/lib/Maypole.pm
index b14720dd7cd262b96b327255881fc7ea51dcfe3d..e71c31f27f155b3fe9f3a41d178345fae071d069 100644 (file)
--- a/lib/Maypole.pm
+++ b/lib/Maypole.pm
@@ -62,7 +62,12 @@ sub handler {
     # See Maypole::Workflow before trying to understand this.
     my ( $class, $req ) = @_;
     $class->init unless $class->init_done;
-    my $r = bless { template_args => {}, config => $class->config }, $class;
+
+    # Create the request object
+    my $r = bless {
+        template_args => {},
+        config        => $class->config
+    }, $class;
     $r->headers_out(Maypole::Headers->new);
     $r->get_request($req);
     $r->parse_location();
@@ -189,6 +194,24 @@ sub parse_path {
     $self->{args}   = \@pi;
 }
 
+sub param { # like CGI::param(), but read-only
+    my $r = shift;
+    my ($key) = @_;
+    if (defined $key) {
+        unless (exists $r->{params}{$key}) {
+            return wantarray() ? () : undef;
+        }
+        my $val = $r->{params}{$key};
+        if (wantarray()) {
+            return ref $val ? @$val : $val;
+        } else {
+            return ref $val ? $val->[0] : $val;
+        }
+    } else {
+        return keys %{$r->{params}};
+    }
+}
+
 sub get_template_root { "." }
 sub get_request       { }
 
@@ -210,8 +233,22 @@ See L<Maypole::Application>.
 
 =head1 DESCRIPTION
 
-This documents the Maypole request object. For user documentation, see
-L<Maypole::Manual>.
+This documents the Maypole request object. See the L<Maypole::Manual>, for a
+detailed guide to using Maypole.
+
+Maypole is a Perl web application framework to Java's struts. It is 
+essentially completely abstracted, and so doesn't know anything about
+how to talk to the outside world.
+
+To use it, you need to create a package which represents your entire
+application. In our example above, this is the C<BeerDB> package.
+
+This needs to first use L<Maypole::Application> which will make your package
+inherit from the appropriate platform driver such as C<Apache::MVC> or
+C<CGI::Maypole>, and then call setup.  This sets up the model classes and
+configures your application. The default model class for Maypole uses
+L<Class::DBI> to map a database to classes, but this can be changed by altering
+configuration. (B<Before> calling setup.)
 
 =head2 CLASS METHODS
 
@@ -311,7 +348,7 @@ will be an array reference.
 
 =head3 get_template_root
 
-Implimentation-specific path to template root.
+Implementation-specific path to template root.
 
 You should only need to define this method if you are writing a new
 Maypole
@@ -328,7 +365,7 @@ or CGI request object, it defaults to blank.
 
 Returns a Maypole::Constant to indicate whether the request is valid.
 
-The default implimentation checks that C<$r-E<gt>table> is publicly
+The default implementation checks that C<$r-E<gt>table> is publicly
 accessible
 and that the model class is configured to handle the C<$r-E<gt>action>
 
@@ -338,7 +375,7 @@ Returns a Maypole::Constant to indicate whether the user is
 authenticated for
 the Maypole request.
 
-The default implimentation returns C<OK>
+The default implementation returns C<OK>
 
 =head3 model_class
 
@@ -417,9 +454,9 @@ authenticate method of your Maypole application.
 
 =head3 call_exception
 
-This model is called to catch exceptions, first after authenticate
-,then after processing the model class, and finally to check for
-exceptions from the view class.
+This model is called to catch exceptions, first after authenticate, then after
+processing the model class, and finally to check for exceptions from the view
+class.
 
 This method first checks if the relevant model class
 can handle exceptions the user, or falls back to the default
@@ -437,20 +474,20 @@ This is the core of maypole. You don't want to know.
 
 =head1 SEE ALSO
 
-There's more documentation, examples, and a wiki at the Maypole web
-site:
+There's more documentation, examples, and a information on our mailing lists
+at the Maypole web site:
 
-http://maypole.perl.org/
+L<http://maypole.perl.org/>
 
-L<Maypole::Application>,L<Apache::MVC>, L<CGI::Maypole>.
+L<Maypole::Application>, L<Apache::MVC>, L<CGI::Maypole>.
 
 =head1 AUTHOR
 
-Sebastian Riedel, c<sri@oook.de>
+Maypole is currently maintained by Simon Flack C<simonflk#cpan.org>
 
 =head1 AUTHOR EMERITUS
 
-Simon Cozens, C<simon@cpan.org>
+Simon Cozens, C<simon#cpan.org>
 
 =head1 THANKS TO