1Maypole::Manual::WorkflUoswe(r3)Contributed Perl DocumenMtaaytpioolne::Manual::Workflow(3)
2
6 Maypole::Manual::Workflow - Maypole's Request Workflow
7
9 This chapter describes the progress of a request through Maypole.
10 An application based on "Maypole" provides an Apache or CGI handler,
12 and eventually delivers a page. This document explains how that hap‐
13 pens, and how to influence it. We'll use the "BeerDB" project as our
14 example. Here's a diagram that gives an overview:
15 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 Initialize class
37 When the first request comes in, the application class will call its
39 own "init" method, inherited from Maypole. This creates a new view
40 object.
41 Construction
43 Once we have initialized, the handler obtains the configuration for
45 your class, and puts it into a new object. We'll call this a request
46 object for the purposes of this document; it will be a new "BeerDB"
47 object.
48 Getting the request
50 Next, the handler calls "get_request" on the new object to have it
52 store a copy of the "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 "Apache::Request" object, and possibly also subclass the
55 next stage too to get more control over what methods are called on your
56 "A::R"-lookalike. "get_request" is expected to put the object in the
57 "ar" slot of the request object.
58 Handling the URL
60 Typically, the details of the request will be passed in the URL. This
62 is done with the "parse_location" method, which is expected to populate
63 several slots of the request object. First, "table" and "action" should
64 be populated with the name of the table and the action parts of the
65 URL. Any other arguments should be placed in a listref in the "args"
66 slot, and GET and POST parameters should be arranged into a hash and
67 placed in the "query" and "params" slots, respectively.
68 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
71 need to provide your own default templates to construct links using
72 your preferred format.
73 Is this an applicable URL?
75 Next, the "is_applicable" method works out if this is actually some‐
77 thing that "Maypole" should care about - whether the class exists in
78 the application, whether it supports the given action, and so on. The
79 action is "supported" if it exists in the model class (or its ances‐
80 tors) and is marked with the ":Exported" attribute; this stops web
81 users from firing off random subroutines in your code.
82 This should return an Apache status code; "OK" if the request should
84 proceed, "DECLINED" if it should be passed on to the default handlers,
85 or whatever other codes for permissions problems.
86 Are we allowed to do this?
88 We then look for an appropriate "authenticate" method to call; first it
90 will try calling the "authenticate" method of the model class, or, if
91 that does not exist, the "authenticate" method on itself. By default,
92 this allows access to everyone for everything. Your "authenticate"
93 methods must return an Apache status code: "OK" or "DECLINED". These
94 codes are defined by the Maypole::Constants module, which is automati‐
95 cally used by your application.
96 Add any additional data to the request
98 You can write an "additional_data" method to do any additional fiddling
100 with the request object before it is despatched. Specifically, it
101 allows you to add to the "template_args" slot, which is a hash of argu‐
102 ments to be added to the template, like this:
103 sub additional_data {
105 my $self = shift;
106 $self->{template_args}{answer} = 42;
107 }
108 which adds a new template variable "answer" with the value 42.
110 Ask model for widget set
112 Asking the model class to "process" the current request allows it to do
114 any work it needs for the given command, and populate the "objects" and
115 "template" slots of the request.
116 The model's "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 "objects" with an object of that class whose ID comes
120 from the URL arguments if there is one. For instance, "/beer/foo/12"
121 will do the moral equivalent of
122 $r->objects([ BeerDB::Beer->retrieve(12) ]);
124 Then it calls the right method: in this case, the "foo" method with the
126 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 Ask view to process template
131 Now the view class has its "process" method called. It finds the appro‐
133 priate templates and calls the Template Toolkit processor.
134 The template processor is handed the objects, the template name, and
136 various other bits and pieces, and tries to find the right template. It
137 does this by looking first for "/beer/foo": that is, a specific tem‐
138 plate appropriate to the class. Next, it looks at "/custom/foo", a
139 local modification, before looking for "/factory/foo", one of the
140 default templates that came with "Maypole".
141 The view puts the template's output in the "$r->{output}" slot. The
143 application's "handler" method calls the "send_output" method to push
144 it to the web server.
145 Default template arguments
147 If you're looking for the list of variables that are passed to the Tem‐
149 plate Toolkit template by default, you'll find it in the View chapter.
150 Links
152 Contents, Next The Beer Database Revisited, Previous Standard Templates
154 and Actions
155perl v5.8.8 2005-11-23 Maypole::Manual::Workflow(3)