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. Specifically, it allows
  99 you to add to the C<template_args> slot, which is a hash of arguments to
 100 be added to the template.
 101
 102 =head2 Ask model for widget set
 103
 104 Asking the model class to C<process> the current request allows it to do
 105 any work it needs for the given command, and populate the C<objects> and
 106 C<template> slots of the request.
 107
 108 =head2 Ask view to process template
 109
 110 Now the view class has its C<process> method called, finds the
 111 appropriate templates, passes the C<objects> and any additional data to
 112 the template, and pushes the output to the web server.
 113
 114 We will go into more detail about these last two phases.
 115
 116 =head1 Model class processing
 117
 118 The model's C<process> method is usually a thin wrapper around the
 119 action that we have selected. It sets the template name to the name of
 120 the action, fills C<objects> with an object of that class whose ID comes
 121 from the URL arguments if there is one. For instance, C</beer/foo/12>
 122 will do the moral equivalent of
 123
 124     $r->objects([ BeerDB::Beer->retrieve(12) ]);
 125
 126 Then it calls the right method: in this case, the C<foo> method with
 127 the request object. This method will usually do any actions which are
 128 required, including modifying the list of objects to be passed to the
 129 template, or the name of the template to be called.
 130
 131 =head1 Template class processing
 132
 133 Finally, the template processor is handed the objects, the template
 134 name, and various other bits and pieces, and tries to find the right
 135 template. It does this by looking first for C</beer/foo>: that is, a
 136 specific template appropriate to the class. Next, it looks at
 137 C</custom/foo>, a local modification, before looking for
 138 C</factory/foo>, one of the default templates that came with
 139 C<Apache::MVC>.
 140
 141 =head2 Default template arguments
 142
 143 The following things are passed to the Template Toolkit template by
 144 default:
 145
 146 =over 3
 147
 148 =item request
 149
 150 The whole C<Apache::MVC> request object, for people getting really dirty
 151 with the templates.
 152
 153 =item objects
 154
 155 The objects handed to us by the model.
 156
 157 =item base
 158
 159 The base URL of the application.
 160
 161 =item config
 162
 163 The whole configuration hash for the application.
 164
 165 =item classmetadata
 166
 167 A hash consisting of:
 168
 169 C<name> - The name of the model class for the request: e.g. C<BeerDB::Beer>.
 170
 171 C<columns> - The names of the columns in this class.
 172
 173 C<colnames> - A hash mapping between the database's idea of a column
 174 name and a human-readable equivalent. (C<abv> should be mapped to
 175 C<A.B.V.>, perhaps.)
 176
 177 C<related_accessors> - A list of accessors which are not exactly fields
 178 in the table but are related by a has-many relationship. For instance,
 179 breweries have many beers, so C<beers> would appear in the list.
 180
 181 C<moniker> - The human-readable name for the class: C<beer>.
 182
 183 C<plural> - The same, only plural: C<beers>.
 184
 185 C<cgi> - A hash mapping columns and C<HTML::Element> objects
 186 representing a form field for editing that column.
 187
 188 C<description> - (Perhaps) a user-supplied description of the class.
 189
 190 =back
 191
 192 Additionally, depending on the number of objects, there will be an alias
 193 for the C<objects> slot with the name of the moniker or plural moniker.
 194
 195 That sounds a bit tricky, but what it means is that if you look at
 196 C</beer/view/4> then C<beer> will be populated with a C<BeerDB::Beer>
 197 object with ID 4. On the other hand, if you look at C</beer/list> you
 198 can get all the beers in C<beers> as well as in C<objects>.
 199
 200