added missing file

[maypole.git] / lib / Maypole.pm

diff --git a/lib/Maypole.pm b/lib/Maypole.pm
index e16dd829abc76ab7e3c6d1da9b40f0153cfc7e85..587bdc7f56174babce89a7b31d69389bc598bbc0 100644 (file)
--- a/lib/Maypole.pm
+++ b/lib/Maypole.pm
@@ -5,13 +5,15 @@ use strict;
 use warnings;
 use Maypole::Config;
 use Maypole::Constants;
 use warnings;
 use Maypole::Config;
 use Maypole::Constants;

+use Maypole::Headers;

 
 

-our $VERSION = '2.05';
+our $VERSION = '2.10_pre2';

 
 __PACKAGE__->mk_classdata($_) for qw( config init_done view_object );
 __PACKAGE__->mk_accessors(
     qw( ar params query objects model_class template_args output path
 
 __PACKAGE__->mk_classdata($_) for qw( config init_done view_object );
 __PACKAGE__->mk_accessors(
     qw( ar params query objects model_class template_args output path

-      args action template error document_encoding content_type table)
+        args action template error document_encoding content_type table
+        headers_in headers_out )

 );
 __PACKAGE__->config( Maypole::Config->new() );
 __PACKAGE__->init_done(0);
 );
 __PACKAGE__->config( Maypole::Config->new() );
 __PACKAGE__->init_done(0);


@@ -32,7 +34,7 @@ sub setup {
     my $config = $calling_class->config;
     $config->model || $config->model("Maypole::Model::CDBI");
     $config->model->require;
     my $config = $calling_class->config;
     $config->model || $config->model("Maypole::Model::CDBI");
     $config->model->require;

-    die "Couldn't load the model class $config->model: $@" if $@;
+    die "Couldn't load the model class $config->{model}: $@" if $@;

     $config->model->setup_database( $config, $calling_class, @_ );
     for my $subclass ( @{ $config->classes } ) {
         no strict 'refs';
     $config->model->setup_database( $config, $calling_class, @_ );
     for my $subclass ( @{ $config->classes } ) {
         no strict 'refs';


@@ -60,7 +62,13 @@ sub handler {
     # See Maypole::Workflow before trying to understand this.
     my ( $class, $req ) = @_;
     $class->init unless $class->init_done;
     # 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();
     my $status = $r->handler_guts();
     $r->get_request($req);
     $r->parse_location();
     my $status = $r->handler_guts();


@@ -178,13 +186,31 @@ sub exception { return ERROR }
 sub parse_path {
     my $self = shift;
     $self->{path} ||= "frontpage";
 sub parse_path {
     my $self = shift;
     $self->{path} ||= "frontpage";

-    my @pi = split /\//, $self->{path};
-    shift @pi while @pi and !$pi[0];
+    my @pi = $self->{path} =~ m{([^/]+)/?}g;

     $self->{table}  = shift @pi;
     $self->{action} = shift @pi;
     $self->{table}  = shift @pi;
     $self->{action} = shift @pi;

+    $self->{action} ||= "index";

     $self->{args}   = \@pi;
 }
 
     $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       { }
 
 sub get_template_root { "." }
 sub get_request       { }
 


@@ -196,6 +222,13 @@ sub send_output {
     die "Do not use Maypole directly; use Apache::MVC or similar";
 }
 
     die "Do not use Maypole directly; use Apache::MVC or similar";
 }
 

+# Session and Repeat Submission Handling
+
+sub make_random_id {
+    use Maypole::Session;
+    return Maypole::Session::generate_unique_id();
+}
+

 =head1 NAME
 
 Maypole - MVC web application framework
 =head1 NAME
 
 Maypole - MVC web application framework


@@ -206,8 +239,22 @@ See L<Maypole::Application>.
 
 =head1 DESCRIPTION
 
 
 =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 similar 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
 
 
 =head2 CLASS METHODS
 


@@ -276,6 +323,14 @@ A list of remaining parts of the request path after table and action
 have been
 removed
 
 have been
 removed
 

+=head3 headers_in
+
+A L<Maypole::Headers> object containing HTTP headers for the request
+
+=head3 headers_out
+
+A L<HTTP::Headers> object that contains HTTP headers for the output
+

 =head3 parse_args
 
 Turns post data and query string paramaters into a hash of C<params>.
 =head3 parse_args
 
 Turns post data and query string paramaters into a hash of C<params>.


@@ -284,12 +339,15 @@ You should only need to define this method if you are writing a new
 Maypole
 backend.
 
 Maypole
 backend.
 

+=head3 param
+
+An accessor for request parameters. It behaves similarly to CGI::param() for
+accessing CGI parameters.
+

 =head3 params
 
 =head3 params
 

-Returns a hash of request parameters. The source of the parameters may
-vary
-depending on the Maypole backend, but they are usually populated from
-request
+Returns a hash of request parameters. The source of the parameters may vary
+depending on the Maypole backend, but they are usually populated from request

 query string and POST data.
 
 B<Note:> Where muliple values of a parameter were supplied, the
 query string and POST data.
 
 B<Note:> Where muliple values of a parameter were supplied, the


@@ -299,7 +357,7 @@ will be an array reference.
 
 =head3 get_template_root
 
 
 =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
 
 You should only need to define this method if you are writing a new
 Maypole


@@ -316,7 +374,7 @@ or CGI request object, it defaults to blank.
 
 Returns a Maypole::Constant to indicate whether the request is valid.
 
 
 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>
 
 accessible
 and that the model class is configured to handle the C<$r-E<gt>action>
 


@@ -326,7 +384,7 @@ Returns a Maypole::Constant to indicate whether the user is
 authenticated for
 the Maypole request.
 
 authenticated for
 the Maypole request.
 

-The default implimentation returns C<OK>
+The default implementation returns C<OK>

 
 =head3 model_class
 
 
 =head3 model_class
 


@@ -405,14 +463,17 @@ authenticate method of your Maypole application.
 
 =head3 call_exception
 
 
 =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
 exception method of your Maypole application.
 
 
 This method first checks if the relevant model class
 can handle exceptions the user, or falls back to the default
 exception method of your Maypole application.
 

+=head3 make_random_id
+
+returns a unique id for this request can be used to prevent or detect repeat submissions.

 
 =head3 handler
 
 
 =head3 handler
 


@@ -425,26 +486,28 @@ This is the core of maypole. You don't want to know.
 
 =head1 SEE ALSO
 
 
 =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
 
 
 =head1 AUTHOR
 

-Sebastian Riedel, c<sri@oook.de>
+Maypole is currently maintained by Simon Flack C<simonflk#cpan.org>

 
 =head1 AUTHOR EMERITUS
 
 
 =head1 AUTHOR EMERITUS
 

-Simon Cozens, C<simon@cpan.org>
+Simon Cozens, C<simon#cpan.org>
+
+Sebastian Riedel, C<sri#oook.de> maintained Maypole from 1.99_01 to 2.04

 
 =head1 THANKS TO
 
 
 =head1 THANKS TO
 

-Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody Belka, Marcus Ramberg,
-Mickael Joanne, Randal Schwartz, Simon Flack, Steve Simms, Veljko Vidovic
-and all the others who've helped.
+Sebastian Riedel, Danijel Milicevic, Dave Slack, Jesse Sheidlower, Jody Belka,
+Marcus Ramberg, Mickael Joanne, Randal Schwartz, Simon Flack, Steve Simms,
+Veljko Vidovic and all the others who've helped.

 
 =head1 LICENSE
 
 
 =head1 LICENSE