=pod

=head1 NAME

Apache::MVC::Workflow - Describes the progress of a request through Apache::MVC

=head1 SYNOPSIS

                              config $h
                                  |
                            Apache::MVC $r
    Apache::Request               |
         +---- $r->get_request ---+
        $ar                       |
                                  |
                          $r->parse_location
                                  |
                          $r->is_applicable
                                  |
    BeerDB::Beer        $r->call_authenticate
       ->authenticate ------------+------------ $r->authenticate
                                  |
                           $r->find_objects
                                  |
                         $r->additional_data
                                  |
                    $r->model_class->process($r)


=head1 DESCRIPTION

An application based on C<Apache::MVC> will provide an Apache handler,
and eventually deliver a page. This document explains how that happens,
and how to influence it. We'll use the C<BeerDB> project as our example.

=head2 Initialize class

When the first request comes in, the class will call its own
C<init> method. This creates a new view object, sets up inheritance
relationships between the model classes and their parent, and so on.

=head2 Construction

Once we have initialized, the handler obtains the configuration for your
class, and puts it into a new object. We'll call this a request
I<object> for the purposes of this document; it will be a new C<BeerDB>
object.

=head2 Getting the request

Next, the handler calls C<get_request> on the new object to have it
store a copy of the C<Apache::Request>. Of course, if you're not using
Apache, you might want to subclass this method to return something that
looks like an C<Apache::Request> object, and possibly also subclass the
next stage too to get more control over what methods are called on your
C<A::R>-lookalike. C<get_request> is expected to put the object in the
C<ar> slot of the request object.

=head2 Handling the URL

Typically, the details of the request will be passed in the URL. This is
done with the C<parse_location> method, which is expected to populate
several slots of the request object. First, C<table> and C<action>
should be populated with the name of the table and the action parts of
the URL. Any other arguments should be placed in a listref in the
C<args> slot, and GET and POST parameters should be arranged into a hash
and placed in the C<params> slot.

Some people may not like the idea of passing everything around in the
URL; this is the method to override for you. Of course, you'll also need
to provide your own default templates to construct links using your
preferred format.

=head2 Is this an applicable URL?

Next, the C<is_applicable> method works out if this is actually
something that C<Apache::MVC> should care about - whether the class
exists in the application, whether it supports the given action, and so
on. This should return an Apache status code; C<OK> if the request
should proceed, C<DECLINED> if it should be passed on to the default
handlers, or whatever other codes for permissions problems. 

=head2 Are we allowed to do this?

We then look for an appropriate C<authenticate> method to call; first
it will try Calling the C<authenticate> method of the model class, or,
if that does not exist, the C<authenticate> method on itself. By
default, this allows access to everyone for everything. Similarly, this
should return an Apache status code.

=head2 Find the appropriate objects

The C<find_objects> method is called to populate the C<objects> slot of
the request object with the appropriate objects from the model class. 

This takes the right number of arguments off the C<args> slot by
examining the attributes of the method in question. Read more about this
in L<Apache::MVC::Model::Default>.

=head2 Add any additional data to the request

The open-ended C<additional_data> method allows any additional fiddling
with the request object before it is despatched.

=head2 Ask model to take over

The C<process> method of the model class is called with the request
object, and is expected to perform any actions it needs, and then
despatch control to the view.