It would be great to have a bit more documentation for the next release (2.0?)
. So I've drafted up some documentation for the Maypole request API. It should
probably replace the POD in Maypole.pm since it mostly duplicates information
in the doc/ folder. With that in mind I have some other
observations/suggestions:
1. It would be good to move the user guide in docs/ into the lib/ folder under
the Maypole::Tutorial/Manual namespace. This will make sure the user guide is
installed along with the rest of Maypole, and the API docs/user guide will be
able to easily refer to one another with the standard L<NAME> syntax.
2. The code bypasses the accessors in may places (see: grep -r '$r->{' trunk/)
. It would be quite nice if Maypole itself used the accessors/mutators it
provides.
What follows is a *quick draft* to get the ball rolling, comments are welcome.
=head1 NAME
Maypole - MVC web application framework
=head1 SYNOPSIS
See L<Maypole::Application>.
=head1 DESCRIPTION
This documents the Maypole request object. For user documentation, see
L<Maypole::Tutorial>.
=head2 CLASS METHODS
=head3 config
Returns the L<Maypole::Config> object
=head3 setup
My::App->setup();
Initialise the maypole application and model classes. Your application should
call this after setting configuration via L<"config">
=head3 init
You should not call this directly, but you may wish to override this to add
application-specific initialisation.
=head3 view_object
Get/set the Maypole::View object
=head3 debug
sub My::App::debug {1}
Returns the debugging flag. Override this in your application class to
enable/disable debugging.
=head2 INSTANCE METHODS
=head3 parse_location
Turns the backend request (e.g. Apache::MVC, Maypole, CGI) into a Maypole
request. It does this by setting the C<path>, and invoking C<parse_path> and
C<parse_args>.
You should only need to define this method if you are writing a new Maypole
backend.
=head3 path
Returns the request path
=head3 parse_path
Parses the request path and sets the C<args>, C<action> and C<table>
properties
=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 parse_args
Turns post data and query string paramaters into a hash of C<params>.
You should only need to define this method if you are writing a new Maypole
backend.
=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<Note:> Where muliple values of a parameter were supplied, the C<params>
value
will be an array reference.
=head3 get_template_root
Implimentation-specific path to template root.
You should only need to define this method if you are writing a new Maypole
backend. Otherwise, see L<Maypole::Config/"template_root">
=head3 is_applicable
Returns a Maypole::Constant to indicate whether the request is valid.
The default implimentation 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>
=head3 authenticate
Returns a Maypole::Constant to indicate whether the user is authenticated for
the Maypole request.
The default implimentation returns C<OK>
=head3 model_class
Returns the perl package name that will serve as the model for the
request. It corresponds to the request C<table> 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<template_args>.
=head3 objects
Get/set a list of model objects. The objects will be accessible in the view
templates.
If the first item in C<$r-E<gt>args> can be C<retrieve()>d by the model class,
it will be removed from C<args> and the retrieved object will be added to the
C<DEFANGED_objects> list. See L<Maypole::Model> for more information.
=head3 template_args
$r->template_args->{foo} = 'bar';
Get/set a hash of template variables.
=head3 template
Get/set the template to be used by the view. By default, it returns
C<$r-E<gt>action>
=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
Get/set a request error
=head3 output
Get/set the response output. This is usually populated by the view class. You
can skip view processing by setting the C<output>.
=head3 document_encoding
Get/set the output encoding. Default: utf-8.
=head3 content_type
Get/set the output content type. Default: text/html
=head3 send_output
Sends the output and additional headers to the user.
=head1 SEE ALSO
There's more documentation, examples, and a wiki at the Maypole web site:
http://maypole.simon-cozens.org/
L<Maypole::Application>,L<Apache::MVC>, L<CGI::Maypole>.
=head1 MAINTAINER
Sebastian Riedel, c<sri at oook.de>
=head1 AUTHOR
Simon Cozens, C<simon at cpan.org>
=head1 THANK YOU
Danijel Milicevic, Jesse Scheidlower, Jody Belka, Marcus Ramberg,
Mickael Joanne, Simon Flack, Veljko Vidovic and all the others who've helped.
=head1 LICENSE
You may distribute this code under the same terms as Perl itself.
=cut
_______________________________________________
maypole-dev mailing list
maypole-dev at lists.netthink.co.uk
http://lists.netthink.co.uk/listinfo/maypole-dev
This archive was generated by hypermail 2.1.3 : Thu Feb 24 2005 - 22:25:56 GMT