Simon Flack:
> 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.
good idea, done.
>
> 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.
Would be nice, but not very important...
>
> 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
Very nice! Added it, thanks.
btw. the Maypole web site is now http://maypole.perl.org
sebastian
_______________________________________________
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