1Maypole::Manual::WorkflUoswe(r3)Contributed Perl DocumenMtaaytpioolne::Manual::Workflow(3)
2
3
4

NAME

6       Maypole::Manual::Workflow - Maypole's Request Workflow
7

DESCRIPTION

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