lib/Apache/MVC/Workflow.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Apache::MVC::Workflow - Describes the progress of a request through Apache::MVC
   6
   7 =head1 SYNOPSIS
   8
   9                               config $h
  10                                   |
  11                             Apache::MVC $r
  12     Apache::Request               |
  13          +---- $r->get_request ---+
  14         $ar                       |
  15                                   |
  16                           $r->parse_location
  17                                   |
  18                           $r->is_applicable
  19                                   |
  20     BeerDB::Beer        $r->call_authenticate
  21        ->authenticate ------------+------------ $r->authenticate
  22                                   |
  23                            $r->find_objects
  24                                   |
  25                          $r->additional_data
  26                                   |
  27                     $r->model_class->process($r)
  28
  29
  30 =head1 DESCRIPTION
  31
  32 An application based on C<Apache::MVC> will provide an Apache handler,
  33 and eventually deliver a page. This document explains how that happens,
  34 and how to influence it. We'll use the C<BeerDB> project as our example.
  35
  36 =head2 Initialize class
  37
  38 When the first request comes in, the class will call its own
  39 C<init> method. This creates a new view object, sets up inheritance
  40 relationships between the model classes and their parent, and so on.
  41
  42 =head2 Construction
  43
  44 Once we have initialized, the handler obtains the configuration for your
  45 class, and puts it into a new object. We'll call this a request
  46 I<object> for the purposes of this document; it will be a new C<BeerDB>
  47 object.
  48
  49 =head2 Getting the request
  50
  51 Next, the handler calls C<get_request> on the new object to have it
  52 store a copy of the C<Apache::Request>. Of course, if you're not using
  53 Apache, you might want to subclass this method to return something that
  54 looks like an C<Apache::Request> object, and possibly also subclass the
  55 next stage too to get more control over what methods are called on your
  56 C<A::R>-lookalike. C<get_request> is expected to put the object in the
  57 C<ar> slot of the request object.
  58
  59 =head2 Handling the URL
  60
  61 Typically, the details of the request will be passed in the URL. This is
  62 done with the C<parse_location> method, which is expected to populate
  63 several slots of the request object. First, C<table> and C<action>
  64 should be populated with the name of the table and the action parts of
  65 the URL. Any other arguments should be placed in a listref in the
  66 C<args> slot, and GET and POST parameters should be arranged into a hash
  67 and placed in the C<params> slot.
  68
  69 Some people may not like the idea of passing everything around in the
  70 URL; this is the method to override for you. Of course, you'll also need
  71 to provide your own default templates to construct links using your
  72 preferred format.
  73
  74 =head2 Is this an applicable URL?
  75
  76 Next, the C<is_applicable> method works out if this is actually
  77 something that C<Apache::MVC> should care about - whether the class
  78 exists in the application, whether it supports the given action, and so
  79 on. This should return an Apache status code; C<OK> if the request
  80 should proceed, C<DECLINED> if it should be passed on to the default
  81 handlers, or whatever other codes for permissions problems.
  82
  83 =head2 Are we allowed to do this?
  84
  85 We then look for an appropriate C<authenticate> method to call; first
  86 it will try Calling the C<authenticate> method of the model class, or,
  87 if that does not exist, the C<authenticate> method on itself. By
  88 default, this allows access to everyone for everything. Similarly, this
  89 should return an Apache status code.
  90
  91 =head2 Find the appropriate objects
  92
  93 The C<find_objects> method is called to populate the C<objects> slot of
  94 the request object with the appropriate objects from the model class.
  95
  96 This takes the right number of arguments off the C<args> slot by
  97 examining the attributes of the method in question. Read more about this
  98 in L<Apache::MVC::Model::Default>.
  99
 100 =head2 Add any additional data to the request
 101
 102 The open-ended C<additional_data> method allows any additional fiddling
 103 with the request object before it is despatched.
 104
 105 =head2 Ask model to take over
 106
 107 The C<process> method of the model class is called with the request
 108 object, and is expected to perform any actions it needs, and then
 109 despatch control to the view.