--- /dev/null
+=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.
projects / maypole.git / blobdiff