lib/Maypole/Manual/Workflow.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Maypole::Manual::Workflow - Maypole's Request Workflow
   6
   7 =head1 DESCRIPTION
   8
   9 This chapter describes the progress of a request through Maypole.
  10
  11 An application based on C<Maypole> provides an Apache or CGI handler,
  12 and eventually delivers a page. This document explains how that happens,
  13 and how to influence it. We'll use the C<BeerDB> project as our example.
  14 Here's a diagram that gives an overview:
  15
  16                               config $h
  17                                   |
  18                             Maypole $r
  19     Apache::Request               |
  20          +---- $r->get_request ---+
  21         $ar                       |
  22                                   |
  23                           $r->parse_location
  24                                   |
  25                           $r->is_applicable
  26                                   |
  27     BeerDB::Beer        $r->call_authenticate
  28        ->authenticate ------------+------------ $r->authenticate
  29                                   |
  30                          $r->additional_data
  31                                   |
  32                     $r->model_class->process($r)
  33                                   |
  34                      $r->view_object->process($r)
  35
  36 =head2 Initialize class
  37
  38 When the first request comes in, the application class will call its own
  39 C<init> method, inherited from L<Maypole>.
  40 This creates a new view object.
  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<query> and C<params> slots, respectively.
  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<Maypole> 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.
  93 Your C<authenticate> methods must return an Apache status code: C<OK> or
  94 C<DECLINED>. These codes are defined by the L<Maypole::Constants>
  95 module, which is automatically used by your application.
  96
  97 =head2 Add any additional data to the request
  98
  99 You can write an C<additional_data> method to do any additional fiddling
 100 with the request object before it is despatched. Specifically, it allows
 101 you to add to the C<template_args> slot, which is a hash of arguments to
 102 be added to the template, like this:
 103
 104     sub additional_data {
 105         my $self = shift;
 106         $self->{template_args}{answer} = 42;
 107     }
 108
 109 which adds a new template variable C<answer> with the value 42.
 110
 111 =head2 Ask model for widget set
 112
 113 Asking the model class to C<process> the current request allows it to do
 114 any work it needs for the given command, and populate the C<objects> and
 115 C<template> slots of the request.
 116
 117 The model's C<process> method is usually a thin wrapper around the
 118 action that we have selected. It sets the template name to the name of
 119 the action, fills C<objects> with an object of that class whose ID comes
 120 from the URL arguments if there is one. For instance, C</beer/foo/12>
 121 will do the moral equivalent of
 122
 123     $r->objects([ BeerDB::Beer->retrieve(12) ]);
 124
 125 Then it calls the right method: in this case, the C<foo> method with
 126 the request object. This method will usually do any actions which are
 127 required, including modifying the list of objects to be passed to the
 128 template, or the name of the template to be called.
 129
 130 =head2 Ask view to process template
 131
 132 Now the view class has its C<process> method called. It finds the
 133 appropriate templates and calls the L<Template Toolkit|Template>
 134 processor.
 135
 136 The template processor is handed the objects, the template
 137 name, and various other bits and pieces, and tries to find the right
 138 template. It does this by looking first for C</beer/foo>: that is, a
 139 specific template appropriate to the class. Next, it looks at
 140 C</custom/foo>, a local modification, before looking for
 141 C</factory/foo>, one of the default templates that came with
 142 C<Maypole>.
 143
 144 The view puts the template's output in the C<$r-E<gt>{output}> slot. The
 145 application's C<handler> method calls the C<send_output> method to push
 146 it to the web server.
 147
 148 =head2 Default template arguments
 149
 150 If you're looking for the list of variables that are passed to the
 151 Template Toolkit template by default, you'll find it in the
 152 L<View|Maypole::Manual::View> chapter.
 153
 154 =head2 Links
 155
 156 L<Contents|Maypole::Manual>,
 157 Next L<The Beer Database Revisited|Maypole::Manual::Beer>,
 158 Previous
 159 L<Standard Templates and Actions|Maypole::Manual::StandardTemplates>
 160
 161 =cut