$self->{args} = \@pi;
}
+sub get_template_root { "." }
+sub get_request { }
+
+sub parse_location {
+ die "Do not use Maypole directly; use Apache::MVC or similar";
+}
+
+sub send_output {
+ die "Do not use Maypole directly; use Apache::MVC or similar";
+}
+
=head1 NAME
Maypole - MVC web application framework
=head1 SYNOPSIS
-See L<Maypole>.
+See L<Maypole::Application>.
=head1 DESCRIPTION
-A large number of web programming tasks follow the same sort of pattern:
-we have some data in a datasource, typically a relational database. We
-have a bunch of templates provided by web designers. We have a number of
-things we want to be able to do with the database - create, add, edit,
-delete records, view records, run searches, and so on. We have a web
-server which provides input from the user about what to do. Something in
-the middle takes the input, grabs the relevant rows from the database,
-performs the action, constructs a page, and spits it out.
-
-Maypole aims to be the most generic and extensible "something in the
-middle" - an MVC-based web application framework.
-
-An example would help explain this best. You need to add a product
-catalogue to a company's web site. Users need to list the products in
-various categories, view a page on each product with its photo and
-pricing information and so on, and there needs to be a back-end where
-sales staff can add new lines, change prices, and delete out of date
-records. So, you set up the database, provide some default templates
-for the designers to customize, and then write an Apache handler like
-this:
-
- package ProductDatabase;
- use base 'Maypole::Application';
- __PACKAGE__->set_database("dbi:mysql:products");
- ProductDatabase->config->uri_base = "http://your.site/catalogue/";
- ProductDatabase::Product->has_a("category" => ProductDatabase::Category);
- # ...
-
- sub authenticate {
- my ($self, $request) = @_;
- return OK if $request->{ar}->get_remote_host() eq "sales.yourcorp.com";
- return OK if $request->{action} =~ /^(view|list)$/;
- return DECLINED;
- }
- 1;
+This documents the Maypole request object. For user documentation, see
+L<Maypole::Tutorial>.
-You then put the following in your Apache config:
+=head2 CLASS METHODS
- <Location /catalogue>
- SetHandler perl-script
- PerlHandler ProductDatabase
- </Location>
+=head3 config
-And copy the templates found in F<templates/factory> into the
-F<catalogue/factory> directory off the web root. When the designers get
-back to you with custom templates, they are to go in
-F<catalogue/custom>. If you need to do override templates on a
-database-table-by-table basis, put the new template in
-F<catalogue/I<table>>.
+Returns the L<Maypole::Config> object
-This will automatically give you C<add>, C<edit>, C<list>, C<view> and
-C<delete> commands; for instance, a product list, go to
+=head3 setup
- http://your.site/catalogue/product/list
+ My::App->setup();
-For a full example, see the included "beer database" application.
+ Initialise the maypole application and model classes. Your
+ application should
+ call this after setting configuration via L<"config">
-=head1 HOW IT WORKS
+=head3 init
-There's some documentation for the workflow in L<Maypole::Workflow>,
-but the basic idea is that a URL part like C<product/list> gets
-translated into a call to C<ProductDatabase::Product-E<gt>list>. This
-propagates the request with a set of objects from the database, and then
-calls the C<list> template; first, a C<product/list> template if it
-exists, then the C<custom/list> and finally C<factory/list>.
+You should not call this directly, but you may wish to override this to
+add
+application-specific initialisation.
-If there's another action you want the system to do, you need to either
-subclass the model class, and configure your class slightly differently:
+=head3 view_object
- package ProductDatabase::Model;
- use base 'Maypole::Model::CDBI';
+Get/set the Maypole::View object
- sub supersearch :Exported {
- my ($self, $request) = @_;
- # Do stuff, get a bunch of objects back
- $r->objects(\@objects);
- $r->template("template_name");
- }
+=head3 debug
-Then your top-level application package should change the model class:
-(Before calling C<setup>)
+ sub My::App::debug {1}
- ProductDatabase->config->model("ProductDatabase::Model");
+ Returns the debugging flag. Override this in your application class
+ to
+ enable/disable debugging.
-(The C<:Exported> attribute means that the method can be called via the
-URL C</I<table>/supersearch/...>.)
+=head2 INSTANCE METHODS
-Alternatively, you can put the method directly into the specific model
-class for the table:
+=head3 parse_location
- sub ProductDatabase::Product::supersearch :Exported { ... }
+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>.
-By default, the view class uses Template Toolkit as the template
-processor, and the model class uses C<Class::DBI>; it may help you to be
-familiar with these modules before going much further with this,
-although I expect there to be other subclasses for other templating
-systems and database abstraction layers as time goes on. The article at
-C<http://www.perl.com/pub/a/2003/07/15/nocode.html> is a great
-introduction to the process we're trying to automate.
+You should only need to define this method if you are writing a new
+Maypole
+backend.
-=head1 USING MAYPOLE
+=head3 path
-You should probably not use Maypole directly. Maypole is an abstract
-class which does not specify how to communicate with the outside world.
-The most popular subclass of Maypole is L<Apache::MVC>, which interfaces
-the Maypole framework to Apache mod_perl; another important one is
-L<CGI::Maypole>. However, if you just don't care, use Maypole::Application,
-and it will choose the right one for you.
+Returns the request path
-If you are implementing Maypole subclasses, you need to provide at least
-the C<parse_location> and C<send_output> methods. You may also want to
-provide C<get_request> and C<get_template_root>. See the
-L<Maypole::Workflow> documentation for what these are expected to do.
+=head3 parse_path
-=cut
+Parses the request path and sets the C<args>, C<action> and C<table>
+properties
-sub get_template_root { "." }
-sub get_request { }
+=head3 table
-sub parse_location {
- die "Do not use Maypole directly; use Apache::MVC or similar";
-}
+The table part of the Maypole request path
-sub send_output {
- die "Do not use Maypole directly; use Apache::MVC or similar";
-}
+=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<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:
+There's more documentation, examples, and a wiki at the Maypole web
+site:
-http://maypole.simon-cozens.org/
+http://maypole.perl.org/
L<Maypole::Application>,L<Apache::MVC>, L<CGI::Maypole>.
=head1 THANK YOU
Danijel Milicevic, Jesse Scheidlower, Jody Belka, Marcus Ramberg,
-Mickael Joanne, Simon Flack, Veljko Vidovic and all the others who've helped.
+Mickael Joanne, Simon Flack, Veljko Vidovic and all the others who've
+helped.
=head1 LICENSE
projects / maypole.git / blobdiff