From: David Baird Date: Thu, 3 Nov 2005 17:09:42 +0000 (+0000) Subject: Reorganised pod in Maypole.pm, finished doc roadmap, various minor pod updates, moved... X-Git-Tag: 2.11~113 X-Git-Url: https://git.decadent.org.uk/gitweb/?a=commitdiff_plain;h=ad24ffc85f25a9b73a28cd326c3b3caea234adbf;p=maypole.git Reorganised pod in Maypole.pm, finished doc roadmap, various minor pod updates, moved session call to handler() git-svn-id: http://svn.maypole.perl.org/Maypole/trunk@405 48953598-375a-da11-a14b-00016c27c3ee --- diff --git a/lib/Maypole.pm b/lib/Maypole.pm index 53732c4..71e0161 100644 --- a/lib/Maypole.pm +++ b/lib/Maypole.pm @@ -16,18 +16,198 @@ our $VERSION = '2.11'; # including plugins # - double leading underscore - private to the current package +=head1 NAME + +Maypole - MVC web application framework + +=head1 SYNOPSIS + +See L. + +=head1 DESCRIPTION + +This documents the Maypole request object. See the L, 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 driver package which represents your entire +application. This is the C package used as an example in the manual. + +This needs to first use L which will make your package +inherit from the appropriate platform driver such as C or +C. Then, the driver calls C. This sets up the model classes and +configures your application. The default model class for Maypole uses +L to map a database to classes, but this can be changed by altering +configuration (B calling setup.) + + +=head1 DOCUMENTATION AND SUPPORT + +Note that some details in some of these resources may be out of date. + +=over 4 + +=item The Maypole Manual + +The primary documentation is the Maypole manual. This lives in the +C pod documents included with the distribution. + +=item Embedded POD + +Individual packages within the distribution contain (more or less) detailed +reference documentation for their API. + +=item Mailing lists + +There are two mailing lists - maypole-devel and maypole-users - see +http://maypole.perl.org/?MailingList + +=item The Maypole Wiki + +The Maypole wiki provides a useful store of extra documentation - +http://maypole.perl.org + +In particular, there's a FAQ (http://maypole.perl.org/?FAQ) and a cookbook +(http://maypole.perl.org/?Cookbook). Again, certain information on these pages +may be out of date. + +=item Web applications with Maypole + +A tutorial written by Simon Cozens for YAPC::EU 2005 - +http://www.droogs.org/perl/maypole/maypole-tutorial.pdf [228KB]. + +=item A Database-Driven Web Application in 18 Lines of Code + +By Paul Barry, published in Linux Journal, March 2005. + +http://www.linuxjournal.com/article/7937 + +"From zero to Web-based database application in eight easy steps". + +Maypole won a 2005 Linux Journal Editor's Choice Award +(http://www.linuxjournal.com/article/8293) after featuring in this article. + +=item Build Web apps with Maypole + +By Simon Cozens, on IBM's DeveloperWorks website, May 2004. + +http://www-128.ibm.com/developerworks/linux/library/l-maypole/ + +=item Rapid Web Application Deployment with Maypole + +By Simon Cozens, on O'Reilly's Perl website, April 2004. + +http://www.perl.com/pub/a/2004/04/15/maypole.html + +=item Authentication + +Some notes written by Simon Cozens. A little bit out of date, but still +very useful: http://www.droogs.org/perl/maypole/authentication.html + +=item CheatSheet + +There's a refcard for the Maypole (and Class::DBI) APIs on the wiki - +http://maypole.perl.org/?CheatSheet. Probably a little out of date now - it's a +wiki, so feel free to fix any errors! + +=item Plugins and add-ons + +There are a large and growing number of plugins and other add-on modules +available on CPAN - http://search.cpan.org/search?query=maypole&mode=module + +=item del.icio.us + +You can find a range of useful Maypole links, particularly to several thoughtful +blog entries, starting here: http://del.icio.us/search/?all=maypole + +=item CPAN ratings + +There are a couple of short reviews here: +http://cpanratings.perl.org/dist/Maypole + +=back + +=head1 DEMOS + +A couple of demos are available, sometimes with source code and configs. + +=over 4 + +=item http://maypole.perl.org/beerdb/ + +The standard BeerDB example, using the TT factory templates supplied in the +distribution. + +=item beerdb.riverside-cms.co.uk + +The standard BeerDB example, running on Mason, using the factory templates +supplied in the L distribution. + +=item beerfb.riverside-cms.co.uk + +A demo of L. This site is running on the set of Mason +templates included in the L distribution. See the +synopsis of L for an example driver + +=back + +=cut + __PACKAGE__->mk_classdata($_) for qw( config init_done view_object ); + __PACKAGE__->mk_accessors( qw( params query objects model_class template_args output path args action template error document_encoding content_type table headers_in headers_out stash session) ); + __PACKAGE__->config( Maypole::Config->new() ); + __PACKAGE__->init_done(0); -sub debug { 0 } +=head1 CLASS METHODS + +=over 4 + +=item config + +Returns the L object + +=item setup + + My::App->setup($data_source, $user, $password, \%attr); + +Initialise the Maypole application and plugins and model classes - see +L. + +If your model is based on L, the C<\%attr> hashref can +contain options that are passed directly to L, to control +how the model hierarchy is constructed. + +Your application should call this B setting up configuration data via +L<"config">. + +=cut + +sub setup +{ + my $class = shift; + + $class->setup_model(@_); +} + +=item setup_model + +Called by C. This method builds the Maypole model hierarchy. + +A likely target for over-riding, if you need to build a customised model. + +=cut -sub setup +sub setup_model { my $calling_class = shift; @@ -48,9 +228,24 @@ sub setup unshift @{ $subclass . "::ISA" }, $config->model; $config->model->adopt($subclass) if $config->model->can("adopt"); + + # TODO: I think we should also load these classes, in case there is any + # custom code. It would save the developer from needing to put + # lots of use MyApp::SomeTable statements in the driver, and should + # help eliminate some of those annoying silent errors if there's a + # syntax error. } } +=item init + +Loads the view class and instantiates the view object. + +You should not call this directly, but you may wish to override this to add +application-specific initialisation - see L. + +=cut + sub init { my $class = shift; @@ -62,9 +257,14 @@ sub init || $config->display_tables( $class->config->tables ); $class->view_object( $class->config->view->new ); $class->init_done(1); - } +=item new + +Constructs a very minimal new Maypole request object. + +=cut + sub new { my ($class) = @_; @@ -77,10 +277,53 @@ sub new return $self; } +=item view_object + +Get/set the Maypole::View object + +=item debug + + sub My::App::debug {1} + +Returns the debugging flag. Override this in your application class to +enable/disable debugging. + +You can also set the C flag via L. + +=cut + +sub debug { 0 } + +=item get_template_root + +Implementation-specific path to template root. + +You should only need to define this method if you are writing a new Maypole +backend. Otherwise, see L + +=cut + +sub get_template_root {'.'} + +=back + +=head1 INSTANCE METHODS + +=head2 Workflow + +=over 4 + +=item handler + +This method sets up the class if it's not done yet, sets some defaults and +leaves the dirty work to C. + +=cut + # handler() has a method attribute so that mod_perl will invoke # BeerDB->handler() as a method rather than a plain function # BeerDB::handler() and so this inherited implementation will be -# found. See e.g. "Practical mod_perl" by Bekman & Cholet for +# found. See e.g. "Practical mod_perl" by Bekman & Cholet for # more information sub handler : method { @@ -96,7 +339,13 @@ sub handler : method $self->get_request($req); $self->parse_location; - my $status = $self->handler_guts; + # hook useful for declining static requests e.g. images + my $status = $self->start_request_hook; + return $status unless $status == Maypole::Constants::OK(); + + $self->session($self->get_session); + + $status = $self->handler_guts; # moving this here causes unit test failures - need to check why # before committing the move @@ -104,11 +353,21 @@ sub handler : method return $status unless $status == OK; + # TODO: require send_output to return a status code $self->send_output; return $status; } +=item handler_guts + +This is the main request handling method and calls various methods to handle the +request/response and defines the workflow within Maypole. + +B. + +=cut + # The root of all evil sub handler_guts { @@ -120,8 +379,6 @@ sub handler_guts $self->__setup_plain_template unless $applicable; - $self->session($self->call_get_session); - my $status; eval { $status = $self->call_authenticate }; @@ -173,6 +430,12 @@ sub handler_guts return $self->__call_process_view; } +sub __load_model +{ + my ($self) = @_; + $self->model_class( $self->config->model->class_of($self, $self->table) ); +} + # is_applicable() returned false, so set up a plain template. Model processing # will be skipped, but need to remove the model anyway so the template can't # access it. @@ -215,18 +478,72 @@ sub __call_process_view return $status; } -sub __load_model +=item get_request + +You should only need to define this method if you are writing a new +Maypole backend. It should return something that looks like an Apache +or CGI request object, it defaults to blank. + +=cut + +sub get_request { } + +=item parse_location + +Turns the backend request (e.g. Apache::MVC, Maypole, CGI) into a Maypole +request. It does this by setting the C, and invoking C and +C. + +You should only need to define this method if you are writing a new Maypole +backend. + +=cut + +sub parse_location { - my ($self) = @_; - $self->model_class( $self->config->model->class_of($self, $self->table) ); + die "parse_location is a virtual method. Do not use Maypole directly; " . + "use Apache::MVC or similar"; } -# is_applicable() should return true or false, not OK or DECLINED, because -# the return value is never used as the return value from handler(). There's -# probably a lot of code out there supplying the return codes though, so -# instead of changing is_applicable() to return 0 or 1, the return value is -# passed through __to_boolean. I think it helps handler_guts() if we don't -# have multiple sets of return codes being checked for different things -drb. +=item start_request_hook + +This is called immediately after setting up the basic request. The default +method simply returns C. + +Any other return value causes Maypole to abort further processing of the +request. This is useful for filtering out requests for static files, e.g. +images, which should not be processed by Maypole or by the templating engine: + + sub start_request_hook + { + my ($r) = @_; + + return Maypole::Constants::DECLINED if $r->path =~ /\.jpg$/; + return Maypole::Constants::OK; + } + +=cut + +sub start_request_hook { Maypole::Constants::OK } + +=item is_applicable + +B as of version 2.11. If you have overridden it, +please override C instead, and change the return type +from a Maypole:Constant to a true/false value. + +Returns a Maypole::Constant to indicate whether the request is valid. + +=item is_model_applicable + +Returns true or false to indicate whether the request is valid. + +The default implementation checks that C<< $r->table >> is publicly +accessible and that the model class is configured to handle the +C<< $r->action >>. + +=cut + sub is_model_applicable { my ($self) = @_; @@ -258,13 +575,6 @@ sub is_model_applicable { $ok = 1; } -# implements tj's default_table_view(), but there's no _default_table_view() -# or _have_default_table_view() yet -# else -# { -# $ok = $self->default_table_view($self->path, $self->args) -# if $self->_have_default_table_view; -# } if (not $ok) { @@ -286,6 +596,22 @@ sub is_model_applicable return 0; } +=item get_session + +The default method is empty. + +=cut + +sub get_session { } + +=item call_authenticate + +This method first checks if the relevant model class +can authenticate the user, or falls back to the default +authenticate method of your Maypole application. + +=cut + sub call_authenticate { my ($self) = @_; @@ -301,10 +627,29 @@ sub call_authenticate return $self->authenticate($self); } -sub call_get_session { - my ($self) = @_; - return $self->get_session($self); -} +=item authenticate + +Returns a Maypole::Constant to indicate whether the user is authenticated for +the Maypole request. + +The default implementation returns C + +=cut + +sub authenticate { return OK } + + +=item 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 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. + +=cut sub call_exception { @@ -320,265 +665,127 @@ sub call_exception return $self->exception($error); } -sub default_table_view { - my ($self,$path,$args) = @_; - my $path_is_ok = 0; - my $default_table_view = __PACKAGE__->_default_table_view; - # (path class action field) - my @path = $self->{path} =~ m{([^/]+)/?}g; - my $search_value = shift(@path); - if ($default_table_view->{path}) { - if ($default_table_view->{path} eq $search_value) { - $search_value = shift(@path); - } else { - return 0; - } - } +=item exception - $self->{table} = $default_table_view->{class}; - $self->{action} = $default_table_view->{action}; - $self->{args} = [ $search_value,@path ]; - return $path_is_ok; -} +This method is called if any exceptions are raised during the authentication or +model/view processing. It should accept the exception as a parameter and return +a Maypole::Constant to indicate whether the request should continue to be +processed. -sub additional_data { } +=cut -sub authenticate { return OK } +sub exception { return ERROR } -sub get_session { } +=item additional_data -sub exception { return ERROR } +Called before the model processes the request, this method gives you a chance to +do some processing for each request, for example, manipulating C. -sub preprocess_path { }; +=cut -sub parse_path -{ - my ($self) = @_; - - $self->preprocess_path; +sub additional_data { } - $self->path || $self->path('frontpage'); - - my @pi = grep {length} split '/', $self->path; - - $self->table || $self->table(shift @pi); - - $self->action || $self->action( shift @pi or 'index' ); - - $self->args || $self->args(\@pi); -} - - -sub make_path -{ - my $r = shift; - - my %args; - - if (@_ == 1 and ref $_[0] and ref $_[0] eq 'HASH') - { - %args = %{$_[0]}; - } - elsif ( @_ > 1 and @_ < 4 ) - { - $args{table} = shift; - $args{action} = shift; - $args{additional} = shift; - } - else - { - %args = @_; - } - - do { die "no $_" unless $args{$_} } for qw( table action ); - - my $additional = $args{additional} || $args{id}; - - my @add = (); - - if ($additional) - { - # if $additional is a href, make_uri() will transform it into a query - @add = (ref $additional eq 'ARRAY') ? @$additional : ($additional); - } - - my $uri = $r->make_uri($args{table}, $args{action}, @add); - - return $uri->as_string; -} - -sub make_uri -{ - my ($r, @segments) = @_; +=item send_output - my $query = (ref $segments[-1] eq 'HASH') ? pop(@segments) : undef; - - my $base = $r->config->uri_base; - $base =~ s|/$||; - - my $uri = URI->new($base); - $uri->path_segments($uri->path_segments, grep {length} @segments); - - my $abs_uri = $uri->abs('/'); - $abs_uri->query_form($query) if $query; - return $abs_uri; -} - - -# like CGI::param(), but read only -sub param -{ - my ($self, $key) = @_; - - return keys %{$self->params} unless defined $key; - - return unless exists $self->params->{$key}; - - my $val = $self->params->{$key}; - - return ref $val ? @$val : ($val) if wantarray; - - return ref $val ? $val->[0] : $val; -} - -sub get_template_root {'.'} -sub get_request { } - -sub get_protocol { - die "get_protocol is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; -} - -sub parse_location { - die "parse_location is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; -} - -sub redirect_request { - die "parse_location is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; -} - -sub redirect_internal_request { +Sends the output and additional headers to the user. -} +=cut sub send_output { die "send_output is a virtual method. 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 SYNOPSIS - -See L. - -=head1 DESCRIPTION - -This documents the Maypole request object. See the L, 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 driver package which represents your entire -application. In our example above, this is the C package. +=item redirect_request -This needs to first use L which will make your package -inherit from the appropriate platform driver such as C or -C. Then, the driver calls C. This sets up the model classes and -configures your application. The default model class for Maypole uses -L to map a database to classes, but this can be changed by altering -configuration. (B calling setup.) - - -=head1 DOCUMENTATION ROADMAP - -The primary documentation is the Maypole manual. This lives in the -C pod documents included with the distribution. - - -=head1 DEMOS - -A couple of demos are available, usually with source code and configs. +Sets output headers to redirect based on the arguments provided -=over4 +Accepts either a single argument of the full url to redirect to, or a hash of +named parameters : -=item beerdb.riverside-cms.co.uk +$r->redirect_request('http://www.example.com/path'); -Looks to be down at the moment. +or -=item beerfb.riverside-cms.co.uk +$r->redirect_request(protocol=>'https', domain=>'www.example.com', path=>'/path/file?arguments', status=>'302', url=>'..'); -A demo of L. This site is running on the set of Mason -templates included in the L distribution. See the -synopsis of L for an example driver +The named parameters are protocol, domain, path, status and url -=head2 CLASS METHODS +Only 1 named parameter is required but other than url, they can be combined as +required and current values (from the request) will be used in place of any +missing arguments. The url argument must be a full url including protocol and +can only be combined with status. -=head3 config +=cut -Returns the L object +sub redirect_request { + die "redirect_request is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; +} -=head3 setup +=item redirect_internal_request - My::App->setup($data_source, $user, $password, \%attr); +=cut -Initialise the maypole application and model classes. Your application should -call this after setting configuration via L<"config"> +sub redirect_internal_request { -=head3 init +} -You should not call this directly, but you may wish to override this to -add -application-specific initialisation. +=back -=head3 new +=head2 Path processing and manipulation -Constructs a very minimal new Maypole request object. +=over 4 -=head3 view_object +=item path -Get/set the Maypole::View object +Returns the request path -=head3 debug +=item parse_path - sub My::App::debug {1} +Parses the request path and sets the C, C and C +properties. Calls C before parsing path and setting properties. -Returns the debugging flag. Override this in your application class to -enable/disable debugging. +=cut -=head2 INSTANCE METHODS +sub parse_path +{ + my ($self) = @_; + + # Previous versions unconditionally set table, action and args to whatever + # was in @pi (or else to defaults, if @pi is empty). + # Adding preprocess_path(), and then setting table, action and args + # conditionally, broke lots of tests, hence this: + $self->$_(undef) for qw/action table args/; + + $self->preprocess_path; -=head3 parse_location + $self->path || $self->path('frontpage'); + + my @pi = grep {length} split '/', $self->path; + + $self->table || $self->table(shift @pi); + $self->action || $self->action( shift @pi or 'index' ); + $self->args || $self->args(\@pi); +} -Turns the backend request (e.g. Apache::MVC, Maypole, CGI) into a -Maypole -request. It does this by setting the C, and invoking C -and -C. +=item preprocess_path -You should only need to define this method if you are writing a new -Maypole -backend. +Sometimes when you don't want to rewrite or over-ride parse_path but +want to rewrite urls or extract data from them before it is parsed. -=head3 path +This method is called after parse_location has populated the request +information and before parse_path has populated the model and action +information, and is passed the request object. -Returns the request path +You can set action, args or table in this method and parse_path will +then leave those values in place or populate them if not present -=head3 parse_path +=cut -Parses the request path and sets the C, C and C
-properties. Calls preprocess_path before parsing path and setting properties. +sub preprocess_path { }; -=head3 make_path( %args or \%args or @args ) +=item make_path( %args or \%args or @args ) This is the counterpart to C. It generates a path to use in links, form actions etc. To implement your own path scheme, just override @@ -599,19 +806,49 @@ C<$additional> can be a string, an arrayref, or a hashref. An arrayref is expanded into extra path elements, whereas a hashref is translated into a query string. -=head3 preprocess_path +=cut + +sub make_path +{ + my $r = shift; + + my %args; + + if (@_ == 1 and ref $_[0] and ref $_[0] eq 'HASH') + { + %args = %{$_[0]}; + } + elsif ( @_ > 1 and @_ < 4 ) + { + $args{table} = shift; + $args{action} = shift; + $args{additional} = shift; + } + else + { + %args = @_; + } + + do { die "no $_" unless $args{$_} } for qw( table action ); -Sometimes when you don't want to rewrite or over-ride parse_path but -want to rewrite urls or extract data from them before it is parsed. + my $additional = $args{additional} || $args{id}; + + my @add = (); + + if ($additional) + { + # if $additional is a href, make_uri() will transform it into a query + @add = (ref $additional eq 'ARRAY') ? @$additional : ($additional); + } + + my $uri = $r->make_uri($args{table}, $args{action}, @add); + + return $uri->as_string; +} -This method is called after parse_location has populated the request -information and before parse_path has populated the model and action -information, and is passed the request object. -You can set action, args or table in this method and parse_path will -then leave those values in place or populate them if not present -=head3 make_uri( @segments ) +=item make_uri( @segments ) Make a L object given table, action etc. Automatically adds the C. @@ -619,219 +856,198 @@ the C. If the final element in C<@segments> is a hash ref, C will render it as a query string. -=head3 table - -The table part of the Maypole request path - -=head3 action - -The action part of the Maypole request path - -=head3 args - -A list of remaining parts of the request path after table and action -have been -removed - -=head3 headers_in - -A L object containing HTTP headers for the request +=cut -=head3 headers_out +sub make_uri +{ + my ($r, @segments) = @_; -A L object that contains HTTP headers for the output + my $query = (ref $segments[-1] eq 'HASH') ? pop(@segments) : undef; + + my $base = $r->config->uri_base; + $base =~ s|/$||; + + my $uri = URI->new($base); + $uri->path_segments($uri->path_segments, grep {length} @segments); + + my $abs_uri = $uri->abs('/'); + $abs_uri->query_form($query) if $query; + return $abs_uri; +} -=head3 parse_args +=item parse_args Turns post data and query string paramaters into a hash of C. -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 backend. -=head3 param - -An accessor for request parameters. It behaves similarly to CGI::param() for -accessing CGI parameters. - -=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 -query string and POST data. - -B Where muliple values of a parameter were supplied, the -C -value -will be an array reference. - -=head3 get_template_root - -Implementation-specific path to template root. - -You should only need to define this method if you are writing a new -Maypole -backend. Otherwise, see L - -=head3 get_request - -You should only need to define this method if you are writing a new -Maypole backend. It should return something that looks like an Apache -or CGI request object, it defaults to blank. - -=head3 default_table_view - -=head3 is_applicable - -Returns a Maypole::Constant to indicate whether the request is valid. - -B as of version 2.11. If you have overridden it, -please override C instead, and change the return type -from Maypole:Constants to true/false. +=back -=head3 is_model_applicable +=head2 Request properties -Returns true or false to indicate whether the request is valid. +=over 4 -The default implementation checks that C<< $r->table >> is publicly -accessible and that the model class is configured to handle the -C<< $r->action >>. - -=head3 authenticate - -Returns a Maypole::Constant to indicate whether the user is -authenticated for -the Maypole request. - -The default implementation returns C - -=head3 model_class +=item model_class Returns the perl package name that will serve as the model for the request. It corresponds to the request C
attribute. -=head3 additional_data -Called before the model processes the request, this method gives you a -chance -to do some processing for each request, for example, manipulating -C. +=item objects -=head3 objects - -Get/set a list of model objects. The objects will be accessible in the -view +Get/set a list of model objects. The objects will be accessible in the view templates. If the first item in C<$self-Eargs> can be Cd by the model -class, -it will be removed from C and the retrieved object will be added -to the -C list. See L for more information. +class, it will be removed from C and the retrieved object will be added to +the C list. See L for more information. -=head3 template_args +=item template_args $self->template_args->{foo} = 'bar'; Get/set a hash of template variables. -=head3 stash +=item stash A place to put custom application data. Not used by Maypole itself. -=head3 template +=item template Get/set the template to be used by the view. By default, it returns C<$self-Eaction> -=head3 exception -This method is called if any exceptions are raised during the -authentication -or -model/view processing. It should accept the exception as a parameter and -return -a Maypole::Constant to indicate whether the request should continue to -be -processed. - -=head3 error +=item error Get/set a request error -=head3 output +=item output -Get/set the response output. This is usually populated by the view -class. You +Get/set the response output. This is usually populated by the view class. You can skip view processing by setting the C. -=head3 document_encoding +=item table + +The table part of the Maypole request path + +=item action + +The action part of the Maypole request path + +=item args + +A list of remaining parts of the request path after table and action +have been +removed + +=item headers_in + +A L object containing HTTP headers for the request + +=item headers_out + +A L object that contains HTTP headers for the output + +=item document_encoding Get/set the output encoding. Default: utf-8. -=head3 content_type +=item content_type Get/set the output content type. Default: text/html -=head3 send_output +=item get_protocol -Sends the output and additional headers to the user. +Returns the protocol the request was made with, i.e. https -=head3 call_authenticate +=cut -This method first checks if the relevant model class -can authenticate the user, or falls back to the default -authenticate method of your Maypole application. +sub get_protocol { + die "get_protocol is a virtual method. Do not use Maypole directly; use Apache::MVC or similar"; +} +=back -=head3 call_exception +=head2 Request parameters -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. +The source of the parameters may vary depending on the Maypole backend, but they +are usually populated from request query string and POST data. -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. +Maypole supplies several approaches for accessing the request parameters. Note +that the current implementation (via a hashref) of C and C is +likely to change in a future version of Maypole. So avoid direct access to these +hashrefs: -=head3 make_random_id + $r->{params}->{foo} # bad + $r->params->{foo} # better -returns a unique id for this request can be used to prevent or detect repeat -submissions. + $r->{query}->{foo} # bad + $r->query->{foo} # better -=head3 get_protocol + $r->param('foo') # best -Returns the protocol the request was made with, i.e. https +=over 4 -=head3 redirect_request +=item param -Sets output headers to redirect based on the arguments provided +An accessor (get or set) for request parameters. It behaves similarly to +CGI::param() for accessing CGI parameters, i.e. -Accepts either a single argument of the full url to redirect to, or a hash of named parameters : + $r->param # returns list of keys + $r->param($key) # returns value for $key + $r->param($key => $value) # returns old value, sets to new value -$r->redirect_request('http://www.example.com/path'); +=cut -or +sub param +{ + my ($self, $key) = (shift, shift); + + return keys %{$self->params} unless defined $key; + + return unless exists $self->params->{$key}; + + my $val = $self->params->{$key}; + + if (@_) + { + my $new_val = shift; + $self->params->{$key} = $new_val; + } + + return ref $val ? @$val : ($val) if wantarray; + + return ref $val ? $val->[0] : $val; +} -$r->redirect_request(protocol=>'https', domain=>'www.example.com', path=>'/path/file?arguments', status=>'302', url=>'..'); -The named parameters are protocol, domain, path, status and url +=item params -Only 1 named parameter is required but other than url, they can be combined as required and current values (from the request) will be used in place of any missing arguments. The url argument must be a full url including protocol and can only be combined with status. +Returns a hashref of request parameters. -=head3 redirect_internal_request +B Where muliple values of a parameter were supplied, the C value +will be an array reference. + +=item query + +Alias for C. -=head3 handler +=item make_random_id -This method sets up the class if it's not done yet, sets some -defaults and leaves the dirty work to handler_guts. +returns a unique id for this request can be used to prevent or detect repeat +submissions. -=head3 handler_guts +=cut -This is the main request handling method and calls various methods to handle the request/response -and defines the workflow within Maypole. +# Session and Repeat Submission Handling +sub make_random_id { + use Maypole::Session; + return Maypole::Session::generate_unique_id(); +} -Currently undocumented and liable to be refactored without warning. +=back =head1 SEE ALSO diff --git a/lib/Maypole/Manual/Inheritance.pod b/lib/Maypole/Manual/Inheritance.pod index 68f2211..a207405 100644 --- a/lib/Maypole/Manual/Inheritance.pod +++ b/lib/Maypole/Manual/Inheritance.pod @@ -16,8 +16,7 @@ application. + | - +-- --+ - | + +- -+ | + diff --git a/lib/Maypole/Manual/Install.pod b/lib/Maypole/Manual/Install.pod index f2e85a7..1c4067a 100644 --- a/lib/Maypole/Manual/Install.pod +++ b/lib/Maypole/Manual/Install.pod @@ -31,7 +31,12 @@ 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. + +Information on installing under Windows is available from the wiki - +http://maypole.perl.org/?WindowsInstall + +More information of installing under various Linux flavours is available on the +Wiki - http://maypole.perl.org/?LinuxInstall You're also going to need a database server and a web server. For databases, I recommend SQLite (if you install the C module, diff --git a/lib/Maypole/Manual/Terminology.pod b/lib/Maypole/Manual/Terminology.pod index 05b321e..1871910 100644 --- a/lib/Maypole/Manual/Terminology.pod +++ b/lib/Maypole/Manual/Terminology.pod @@ -21,6 +21,13 @@ L to set up your app (not recommended for newbies, but common enough), the driver class will directly inherit from one of Maypole's frontend classes. +=item controller + +Occasionally this term is used in place of C. + +See the entry below (MVC) for the main usage of the term C within +Maypole. + =item application Sometimes this is used to refer to the driver, but this term is best reserved @@ -88,8 +95,12 @@ A file used to generate HTML for part or all of a web page. Maypole currently supports Template Toolkit and Mason as templating languages, but others could be added easily. +=back + =head2 MVC and Maypole +=over 4 + =item MVC - Model-View-Controller A pattern describing separation of concerns in a complex application. The @@ -100,21 +111,22 @@ Opinions vary between how closely Maypole adheres to this pattern. Here's one opinion: -=over 4 - =item controller An abstract concept in Maypole, i.e. there is no specific controller class. -The main sequence of events that occur during the processing of a request is -controlled by methods in L. Thus, major parts of the controller are in -the same class as the request object. This may seem a bit strange, but in +The main sequence of events that occur during the processing of a request is +controlled by methods in C. Thus, major parts of the controller are +in the same class as the request object. This may seem a bit strange, but in practice it works well. More detailed events within the processing of a request are actually handled by methods in the Maypole 'model'. For instance, switching from one template to another. +Be aware that occasionally authors refer to the C when they are +describing the C. + =item model In Maypole, the model is the set of classes representing individual tables in diff --git a/t/maypole.t b/t/maypole.t index 1941839..4a0cd02 100755 --- a/t/maypole.t +++ b/t/maypole.t @@ -1,7 +1,7 @@ #!/usr/bin/perl use strict; use warnings; -use Test::More tests => 74; +use Test::More tests => 84; use Test::MockModule; # module compilation @@ -23,14 +23,16 @@ my $DECLINED = Maypole::Constants::DECLINED(); my $ERROR = Maypole::Constants::ERROR(); # Maypole API -my @API = qw/ config init_done view_object params query objects model_class +my @API = qw/ config init_done view_object params query param objects model_class template_args output path args action template error document_encoding content_type table headers_in headers_out - is_model_applicable setup init handler handler_guts + is_model_applicable setup setup_model init handler handler_guts call_authenticate call_exception additional_data authenticate exception parse_path make_path make_uri get_template_root get_request parse_location send_output + start_request_hook + session get_session /; can_ok(Maypole => @API); @@ -348,6 +350,7 @@ my $mock_table = new Test::MockModule($table_class, no_auto => 1); # parse_path() { $r->path(undef); + $r->parse_path; is($r->path, 'frontpage', '... path() defaults to "frontpage"'); @@ -391,3 +394,38 @@ my $mock_table = new Test::MockModule($table_class, no_auto => 1); eval {Maypole->send_output}; like($@, qr/Do not use Maypole directly/, '... croaks - must be overriden'); } + +# param() +{ + my $p = { foo => 'bar', + quux => [ qw/one two three/ ], + buz => undef, + num => 3, + zero => 0, + }; + + $r->{params} = $p; + + is_deeply( [keys %$p], [$r->param] ); + + cmp_ok( $r->param('foo'), eq => 'bar' ); + cmp_ok( $r->param('num'), '==' => 3 ); + cmp_ok( $r->param('zero'), '==' => 0 ); + + ok( ! defined $r->param('buz') ); + + # scalar context returns the 1st value, not a ref + cmp_ok( scalar $r->param('quux'), eq => 'one' ); + is_deeply( [$r->param('quux')], [ qw/one two three/ ] ); + + $r->param(foo => 'booze'); + cmp_ok( $r->param('foo'), 'eq', 'booze' ); + + $r->param(foo => undef); + ok( ! defined $r->param('foo') ); + + # cannot introduce new keys + $r->param(new => 'sox'); + ok( ! defined $r->param('new') ); +} + diff --git a/t/pathtools.t b/t/pathtools.t index c8e78d0..b148429 100644 --- a/t/pathtools.t +++ b/t/pathtools.t @@ -32,7 +32,6 @@ my $r = $driver_class->new; my $query_string = '?number=4&string=baz&list=fee&list=fi&list=fo'; - # expect # send my @uris = ( { expect =>'', send => [ '' ],