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->additional_data
  24                                   |
  25                     $r->model_class->process($r)
  26                                   |
  27                      $r->view_object->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. The action is "supported" if it exists in the model class (or its
  80 ancestors) and is marked with the C<:Exported> attribute; this stops web
  81 users from firing off random subroutines in your code.
  82
  83 This should return an Apache status code; C<OK> if the request should
  84 proceed, C<DECLINED> if it should be passed on to the default handlers,
  85 or whatever other codes for permissions problems.
  86
  87 =head2 Are we allowed to do this?
  88
  89 We then look for an appropriate C<authenticate> method to call; first
  90 it will try calling the C<authenticate> method of the model class, or,
  91 if that does not exist, the C<authenticate> method on itself. By
  92 default, this allows access to everyone for everything. Similarly, this
  93 should return an Apache status code.
  94
  95 =head2 Add any additional data to the request
  96
  97 The open-ended C<additional_data> method allows any additional fiddling
  98 with the request object before it is despatched.
  99
 100 =head2 Ask model for widget set
 101
 102 Asking the model class to C<process> the current request allows it to do
 103 any work it needs for the given command, and populate the C<objects> and
 104 C<template> slots of the request.
 105
 106 =head2 Ask view to process template
 107
 108 Now the view class has its C<process> method called, finds the
 109 appropriate templates, passes the C<objects> and any additional data to
 110 the template, and pushes the output to the web server.
 111
 112 We will go into more detail about these last two phases.
 113
 114 =head1 Model class processing
 115
 116 The model's C<process> method is usually a thin wrapper around the
 117 action that we have selected.
 118
 119 =head2