1Catalyst::DispatchType:U:sCehraiCnoendt(r3i)buted Perl DCoactuamleynstta:t:iDoinspatchType::Chained(3)
2
3
4

NAME

6       Catalyst::DispatchType::Chained - Path Part DispatchType
7

SYNOPSIS

9       Path part matching, allowing several actions to sequentially take care
10       of processing a request:
11
12         #   root action - captures one argument after it
13         sub foo_setup : Chained('/') PathPart('foo') CaptureArgs(1) {
14             my ( $self, $c, $foo_arg ) = @_;
15             ...
16         }
17
18         #   child action endpoint - takes one argument
19         sub bar : Chained('foo_setup') Args(1) {
20             my ( $self, $c, $bar_arg ) = @_;
21             ...
22         }
23

DESCRIPTION

25       Dispatch type managing default behaviour.  For more information on
26       dispatch types, see:
27
28       •   Catalyst::Manual::Intro for how they affect application authors
29
30       •   Catalyst::DispatchType for implementation information.
31

METHODS

33   $self->list($c)
34       Debug output for Path Part dispatch points
35
36   $self->match( $c, $path )
37       Calls "recurse_match" to see if a chain matches the $path.
38
39   $self->recurse_match( $c, $parent, \@path_parts )
40       Recursive search for a matching chain.
41
42   $self->register( $c, $action )
43       Calls register_path for every Path attribute for the given $action.
44
45   $self->uri_for_action($action, $captures)
46       Get the URI part for the action, using $captures to fill the capturing
47       parts.
48
49   $c->expand_action($action)
50       Return a list of actions that represents a chained action. See
51       Catalyst::Dispatcher for more info. You probably want to use the
52       expand_action it provides rather than this directly.
53

USAGE

55   Introduction
56       The "Chained" attribute allows you to chain public path parts together
57       by their private names. A chain part's path can be specified with
58       "PathPart" and can be declared to expect an arbitrary number of
59       arguments. The endpoint of the chain specifies how many arguments it
60       gets through the "Args" attribute. :Args(0) would be none at all,
61       ":Args" without an integer would be unlimited. The path parts that
62       aren't endpoints are using "CaptureArgs" to specify how many parameters
63       they expect to receive. As an example setup:
64
65         package MyApp::Controller::Greeting;
66         use base qw/ Catalyst::Controller /;
67
68         #   this is the beginning of our chain
69         sub hello : PathPart('hello') Chained('/') CaptureArgs(1) {
70             my ( $self, $c, $integer ) = @_;
71             $c->stash->{ message } = "Hello ";
72             $c->stash->{ arg_sum } = $integer;
73         }
74
75         #   this is our endpoint, because it has no :CaptureArgs
76         sub world : PathPart('world') Chained('hello') Args(1) {
77             my ( $self, $c, $integer ) = @_;
78             $c->stash->{ message } .= "World!";
79             $c->stash->{ arg_sum } += $integer;
80
81             $c->response->body( join "<br/>\n" =>
82                 $c->stash->{ message }, $c->stash->{ arg_sum } );
83         }
84
85       The debug output provides a separate table for chained actions, showing
86       the whole chain as it would match and the actions it contains. Here's
87       an example of the startup output with our actions above:
88
89         ...
90         [debug] Loaded Path Part actions:
91         .-----------------------+------------------------------.
92         | Path Spec             | Private                      |
93         +-----------------------+------------------------------+
94         | /hello/*/world/*      | /greeting/hello (1)          |
95         |                       | => /greeting/world           |
96         '-----------------------+------------------------------'
97         ...
98
99       As you can see, Catalyst only deals with chains as whole paths and
100       builds one for each endpoint, which are the actions with ":Chained" but
101       without ":CaptureArgs".
102
103       Let's assume this application gets a request at the path
104       "/hello/23/world/12". What happens then? First, Catalyst will dispatch
105       to the "hello" action and pass the value 23 as an argument to it after
106       the context. It does so because we have previously used :CaptureArgs(1)
107       to declare that it has one path part after itself as its argument. We
108       told Catalyst that this is the beginning of the chain by specifying
109       :Chained('/'). Also note that instead of saying :PathPart('hello') we
110       could also just have said ":PathPart", as it defaults to the name of
111       the action.
112
113       After "hello" has run, Catalyst goes on to dispatch to the "world"
114       action. This is the last action to be called: Catalyst knows this is an
115       endpoint because we did not specify a ":CaptureArgs" attribute.
116       Nevertheless we specify that this action expects an argument, but at
117       this point we're using :Args(1) to do that. We could also have said
118       ":Args" or left it out altogether, which would mean this action would
119       get all arguments that are there. This action's ":Chained" attribute
120       says "hello" and tells Catalyst that the "hello" action in the current
121       controller is its parent.
122
123       With this we have built a chain consisting of two public path parts.
124       "hello" captures one part of the path as its argument, and also
125       specifies the path root as its parent. So this part is "/hello/$arg".
126       The next part is the endpoint "world", expecting one argument. It sums
127       up to the path part "world/$arg". This leads to a complete chain of
128       "/hello/$arg/world/$arg" which is matched against the requested paths.
129
130       This example application would, if run and called by e.g.
131       "/hello/23/world/12", set the stash value "message" to "Hello" and the
132       value "arg_sum" to "23". The "world" action would then append "World!"
133       to "message" and add 12 to the stash's "arg_sum" value.  For the sake
134       of simplicity no view is shown. Instead we just put the values of the
135       stash into our body. So the output would look like:
136
137         Hello World!
138         35
139
140       And our test server would have given us this debugging output for the
141       request:
142
143         ...
144         [debug] "GET" request for "hello/23/world/12" from "127.0.0.1"
145         [debug] Path is "/greeting/world"
146         [debug] Arguments are "12"
147         [info] Request took 0.164113s (6.093/s)
148         .------------------------------------------+-----------.
149         | Action                                   | Time      |
150         +------------------------------------------+-----------+
151         | /greeting/hello                          | 0.000029s |
152         | /greeting/world                          | 0.000024s |
153         '------------------------------------------+-----------'
154         ...
155
156       What would be common uses of this dispatch technique? It gives the
157       possibility to split up logic that contains steps that each depend on
158       each other. An example would be, for example, a wiki path like
159       "/wiki/FooBarPage/rev/23/view". This chain can be easily built with
160       these actions:
161
162         sub wiki : PathPart('wiki') Chained('/') CaptureArgs(1) {
163             my ( $self, $c, $page_name ) = @_;
164             #  load the page named $page_name and put the object
165             #  into the stash
166         }
167
168         sub rev : PathPart('rev') Chained('wiki') CaptureArgs(1) {
169             my ( $self, $c, $revision_id ) = @_;
170             #  use the page object in the stash to get at its
171             #  revision with number $revision_id
172         }
173
174         sub view : PathPart Chained('rev') Args(0) {
175             my ( $self, $c ) = @_;
176             #  display the revision in our stash. Another option
177             #  would be to forward a compatible object to the action
178             #  that displays the default wiki pages, unless we want
179             #  a different interface here, for example restore
180             #  functionality.
181         }
182
183       It would now be possible to add other endpoints, for example "restore"
184       to restore this specific revision as the current state.
185
186       You don't have to put all the chained actions in one controller. The
187       specification of the parent through ":Chained" also takes an absolute
188       action path as its argument. Just specify it with a leading "/".
189
190       If you want, for example, to have actions for the public paths
191       "/foo/12/edit" and "/foo/12", just specify two actions with
192       :PathPart('foo') and :Chained('/'). The handler for the former path
193       needs a :CaptureArgs(1) attribute and a endpoint with :PathPart('edit')
194       and :Chained('foo'). For the latter path give the action just a
195       :Args(1) to mark it as endpoint. This sums up to this debugging output:
196
197         ...
198         [debug] Loaded Path Part actions:
199         .-----------------------+------------------------------.
200         | Path Spec             | Private                      |
201         +-----------------------+------------------------------+
202         | /foo/*                | /controller/foo_view         |
203         | /foo/*/edit           | /controller/foo_load (1)     |
204         |                       | => /controller/edit          |
205         '-----------------------+------------------------------'
206         ...
207
208       Here's a more detailed specification of the attributes belonging to
209       ":Chained":
210
211   Attributes
212       PathPart
213               Sets the name of this part of the chain. If it is specified
214               without arguments, it takes the name of the action as default.
215               So basically "sub foo :PathPart" and "sub foo :PathPart('foo')"
216               are identical.  This can also contain slashes to bind to a
217               deeper level. An action with "sub bar :PathPart('foo/bar')
218               :Chained('/')" would bind to "/foo/bar/...". If you don't
219               specify ":PathPart" it has the same effect as using
220               ":PathPart", it would default to the action name.
221
222       PathPrefix
223               Sets PathPart to the path_prefix of the current controller.
224
225       Chained Has to be specified for every child in the chain. Possible
226               values are absolute and relative private action paths or a
227               single slash "/" to tell Catalyst that this is the root of a
228               chain. The attribute ":Chained" without arguments also defaults
229               to the "/" behavior.  Relative action paths may use "../" to
230               refer to actions in parent controllers.
231
232               Because you can specify an absolute path to the parent action,
233               it doesn't matter to Catalyst where that parent is located. So,
234               if your design requests it, you can redispatch a chain through
235               any controller or namespace you want.
236
237               Another interesting possibility gives :Chained('.'), which
238               chains itself to an action with the path of the current
239               controller's namespace.  For example:
240
241                 #   in MyApp::Controller::Foo
242                 sub bar : Chained CaptureArgs(1) { ... }
243
244                 #   in MyApp::Controller::Foo::Bar
245                 sub baz : Chained('.') Args(1) { ... }
246
247               This builds up a chain like "/bar/*/baz/*". The specification
248               of "."  as the argument to Chained here chains the "baz" action
249               to an action with the path of the current controller namespace,
250               namely "/foo/bar". That action chains directly to "/", so the
251               "/bar/*/baz/*" chain comes out as the end product.
252
253       ChainedParent
254               Chains an action to another action with the same name in the
255               parent controller. For Example:
256
257                 # in MyApp::Controller::Foo
258                 sub bar : Chained CaptureArgs(1) { ... }
259
260                 # in MyApp::Controller::Foo::Bar
261                 sub bar : ChainedParent Args(1) { ... }
262
263               This builds a chain like "/bar/*/bar/*".
264
265       CaptureArgs
266               Must be specified for every part of the chain that is not an
267               endpoint. With this attribute Catalyst knows how many of the
268               following parts of the path (separated by "/") this action
269               wants to capture as its arguments. If it doesn't expect any,
270               just specify :CaptureArgs(0).  The captures get passed to the
271               action's @_ right after the context, but you can also find them
272               as array references in "$c->request->captures->[$level]". The
273               $level is the level of the action in the chain that captured
274               the parts of the path.
275
276               An action that is part of a chain (that is, one that has a
277               ":Chained" attribute) but has no ":CaptureArgs" attribute is
278               treated by Catalyst as a chain end.
279
280               Allowed values for CaptureArgs is a single integer
281               (CaptureArgs(2), meaning two allowed) or you can declare a
282               Moose, MooseX::Types or Type::Tiny named constraint such as
283               CaptureArgs(Int,Str) would require two args with the first
284               being a Integer and the second a string.  You may declare your
285               own custom type constraints and import them into the controller
286               namespace:
287
288                   package MyApp::Controller::Root;
289
290                   use Moose;
291                   use MooseX::MethodAttributes;
292                   use MyApp::Types qw/Int/;
293
294                   extends 'Catalyst::Controller';
295
296                   sub chain_base :Chained(/) CaptureArgs(1) { }
297
298                     sub any_priority_chain :Chained(chain_base) PathPart('') Args(1) { }
299
300                     sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
301
302               If you use a reference type constraint in CaptureArgs, it must
303               be a type like Tuple in Types::Standard that allows us to
304               determine the number of args to match.  Otherwise this will
305               raise an error during startup.
306
307               See Catalyst::RouteMatching for more.
308
309       Args    By default, endpoints receive the rest of the arguments in the
310               path. You can tell Catalyst through ":Args" explicitly how many
311               arguments your endpoint expects, just like you can with
312               ":CaptureArgs". Note that this also affects whether this chain
313               is invoked on a request. A chain with an endpoint specifying
314               one argument will only match if exactly one argument exists in
315               the path.
316
317               You can specify an exact number of arguments like :Args(3),
318               including 0. If you just say ":Args" without any arguments, it
319               is the same as leaving it out altogether: The chain is matched
320               regardless of the number of path parts after the endpoint.
321
322               Just as with ":CaptureArgs", the arguments get passed to the
323               action in @_ after the context object. They can also be reached
324               through "$c->request->arguments".
325
326               You should see 'Args' in Catalyst::Controller for more details
327               on using type constraints in your Args declarations.
328
329   Auto actions, dispatching and forwarding
330       Note that the list of "auto" actions called depends on the private path
331       of the endpoint of the chain, not on the chained actions way. The
332       "auto" actions will be run before the chain dispatching begins. In
333       every other aspect, "auto" actions behave as documented.
334
335       The "forward"ing to other actions does just what you would expect. i.e.
336       only the target action is run. The actions that that action is chained
337       to are not run.  If you "detach" out of a chain, the rest of the chain
338       will not get called after the "detach".
339
340   match_captures
341       A method which can optionally be implemented by actions to stop chain
342       matching.
343
344       See Catalyst::Action for further details.
345

AUTHORS

347       Catalyst Contributors, see Catalyst.pm
348
350       This library is free software. You can redistribute it and/or modify it
351       under the same terms as Perl itself.
352
353
354
355perl v5.36.0                      2023-01-20Catalyst::DispatchType::Chained(3)
Impressum