X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=lib%2FApache%2FMVC%2FWorkflow.pod;h=15d87c03120d15bb6c93424870eebd9861240915;hb=5cccc5a89004f9c514e9d611b5e2a02e9aa28ece;hp=09031c00da86c2b0da10c19f6c6d5eb519c09676;hpb=1b3ec28e5f2b7f6f5f4c8140a98e114912271a53;p=maypole.git

diff --git a/lib/Apache/MVC/Workflow.pod b/lib/Apache/MVC/Workflow.pod
index 09031c0..15d87c0 100644
--- a/lib/Apache/MVC/Workflow.pod
+++ b/lib/Apache/MVC/Workflow.pod
@@ -20,11 +20,11 @@ Apache::MVC::Workflow - Describes the progress of a request through Apache::MVC
     BeerDB::Beer        $r->call_authenticate
        ->authenticate ------------+------------ $r->authenticate
                                   |
-                           $r->find_objects
-                                  |
                          $r->additional_data
                                   |
                     $r->model_class->process($r)
+                                  |
+                     $r->view_object->process($r)
 
 
 =head1 DESCRIPTION
@@ -64,7 +64,7 @@ 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.
+and placed in the C<query> and C<params> slots, respectively.
 
 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
@@ -76,34 +76,125 @@ preferred format.
 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. 
+on. The action is "supported" if it exists in the model class (or its
+ancestors) and is marked with the C<:Exported> attribute; this stops web
+users from firing off random subroutines in your code.
+
+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,
+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
+=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. Specifically, it allows
+you to add to the C<template_args> slot, which is a hash of arguments to
+be added to the template.
 
-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. 
+=head2 Ask model for widget set
 
-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>.
+Asking the model class to C<process> the current request allows it to do
+any work it needs for the given command, and populate the C<objects> and
+C<template> slots of the request. 
 
-=head2 Add any additional data to the request
+=head2 Ask view to process template
 
-The open-ended C<additional_data> method allows any additional fiddling
-with the request object before it is despatched.
+Now the view class has its C<process> method called, finds the
+appropriate templates, passes the C<objects> and any additional data to
+the template, and pushes the output to the web server.
+
+We will go into more detail about these last two phases.
+
+=head1 Model class processing
+
+The model's C<process> method is usually a thin wrapper around the
+action that we have selected. It sets the template name to the name of
+the action, fills C<objects> with an object of that class whose ID comes
+from the URL arguments if there is one. For instance, C</beer/foo/12>
+will do the moral equivalent of
+
+    $r->objects([ BeerDB::Beer->retrieve(12) ]);
+
+Then it calls the right method: in this case, the C<foo> method with
+the request object. This method will usually do any actions which are
+required, including modifying the list of objects to be passed to the
+template, or the name of the template to be called.
+
+=head1 Template class processing
+
+Finally, the template processor is handed the objects, the template
+name, and various other bits and pieces, and tries to find the right
+template. It does this by looking first for C</beer/foo>: that is, a
+specific template appropriate to the class. Next, it looks at
+C</custom/foo>, a local modification, before looking for
+C</factory/foo>, one of the default templates that came with
+C<Apache::MVC>.
+
+=head2 Default template arguments
+
+The following things are passed to the Template Toolkit template by
+default:
+
+=over 3
+
+=item request
+
+The whole C<Apache::MVC> request object, for people getting really dirty
+with the templates.
+
+=item objects
+
+The objects handed to us by the model.
+
+=item base
+
+The base URL of the application.
+
+=item config
+
+The whole configuration hash for the application.
+
+=item classmetadata
+
+A hash consisting of:
+
+C<name> - The name of the model class for the request: e.g. C<BeerDB::Beer>.
+
+C<columns> - The names of the columns in this class.
+
+C<colnames> - A hash mapping between the database's idea of a column
+name and a human-readable equivalent. (C<abv> should be mapped to
+C<A.B.V.>, perhaps.)
+
+C<related_accessors> - A list of accessors which are not exactly fields
+in the table but are related by a has-many relationship. For instance,
+breweries have many beers, so C<beers> would appear in the list.
+
+C<moniker> - The human-readable name for the class: C<beer>.
+
+C<plural> - The same, only plural: C<beers>.
+
+C<cgi> - A hash mapping columns and C<HTML::Element> objects
+representing a form field for editing that column.
+
+C<description> - (Perhaps) a user-supplied description of the class.
+
+=back
+
+Additionally, depending on the number of objects, there will be an alias
+for the C<objects> slot with the name of the moniker or plural moniker.
+
+That sounds a bit tricky, but what it means is that if you look at
+C</beer/view/4> then C<beer> will be populated with a C<BeerDB::Beer>
+object with ID 4. On the other hand, if you look at C</beer/list> you
+can get all the beers in C<beers> as well as in C<objects>.
 
-=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.