Mojolicious::Routes::Route(3pm)

1Mojolicious::Routes::RoUusteer(3C)ontributed Perl DocumeMnotjaotliiocnious::Routes::Route(3)
2
3
4

NAME

6       Mojolicious::Routes::Route - Route
7

SYNOPSIS

9         use Mojolicious::Routes::Route;
10
11         my $r = Mojolicious::Routes::Route->new;
12

DESCRIPTION

14       Mojolicious::Routes::Route is the route container used by
15       Mojolicious::Routes.
16

ATTRIBUTES

18       Mojolicious::Routes::Route implements the following attributes.
19
20   children
21         my $children = $r->children;
22         $r           = $r->children([Mojolicious::Routes::Route->new]);
23
24       The children of this route, used for nesting routes.
25
26   inline
27         my $bool = $r->inline;
28         $r       = $r->inline($bool);
29
30       Allow "under" semantics for this route.
31
32   parent
33         my $parent = $r->parent;
34         $r         = $r->parent(Mojolicious::Routes::Route->new);
35
36       The parent of this route, usually a Mojolicious::Routes::Route object.
37       Note that this attribute is weakened.
38
39   partial
40         my $bool = $r->partial;
41         $r       = $r->partial($bool);
42
43       Route has no specific end, remaining characters will be captured in
44       "path".
45
46   pattern
47         my $pattern = $r->pattern;
48         $r          = $r->pattern(Mojolicious::Routes::Pattern->new);
49
50       Pattern for this route, defaults to a Mojolicious::Routes::Pattern
51       object.
52

METHODS

54       Mojolicious::Routes::Route inherits all methods from Mojo::Base and
55       implements the following new ones.
56
57   add_child
58         $r = $r->add_child(Mojolicious::Routes::Route->new);
59
60       Add a child to this route, it will be automatically removed from its
61       current parent if necessary.
62
63         # Reattach route
64         $r->add_child($r->find('foo'));
65
66   any
67         my $route = $r->any;
68         my $route = $r->any('/:foo');
69         my $route = $r->any('/:foo' => sub ($c) {...});
70         my $route = $r->any('/:foo' => sub ($c) {...} => 'name');
71         my $route = $r->any('/:foo' => {foo => 'bar'} => sub ($c) {...});
72         my $route = $r->any('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
73         my $route = $r->any('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
74         my $route = $r->any(['GET', 'POST'] => '/:foo' => sub ($c) {...});
75         my $route = $r->any(['GET', 'POST'] => '/:foo' => [foo => qr/\w+/]);
76
77       Generate Mojolicious::Routes::Route object matching any of the listed
78       HTTP request methods or all.
79
80         # Route with pattern and destination
81         $r->any('/user')->to('user#whatever');
82
83       All arguments are optional, but some have to appear in a certain order,
84       like the two supported array reference values, which contain the HTTP
85       methods to match and restrictive placeholders.
86
87         # Route with HTTP methods, pattern, restrictive placeholders and destination
88         $r->any(['DELETE', 'PUT'] => '/:foo' => [foo => qr/\w+/])->to('foo#bar');
89
90       There are also two supported string values, containing the route
91       pattern and the route name, defaulting to the pattern "/" and a name
92       based on the pattern.
93
94         # Route with pattern, name and destination
95         $r->any('/:foo' => 'foo_route')->to('foo#bar');
96
97       An arbitrary number of key/value pairs in between the route pattern and
98       name can be used to specify route conditions.
99
100         # Route with pattern, condition and destination
101         $r->any('/' => (agent => qr/Firefox/))->to('foo#bar');
102
103       A hash reference is used to specify optional placeholders and default
104       values for the stash.
105
106         # Route with pattern, optional placeholder and destination
107         $r->any('/:foo' => {foo => 'bar'})->to('foo#bar');
108
109       And a code reference can be used to specify a "cb" value to be merged
110       into the default values for the stash.
111
112         # Route with pattern and a closure as destination
113         $r->any('/:foo' => sub ($c) {
114           $c->render(text => 'Hello World!');
115         });
116
117       See Mojolicious::Guides::Tutorial and Mojolicious::Guides::Routing for
118       more information.
119
120   delete
121         my $route = $r->delete;
122         my $route = $r->delete('/:foo');
123         my $route = $r->delete('/:foo' => sub ($c) {...});
124         my $route = $r->delete('/:foo' => sub ($c) {...} => 'name');
125         my $route = $r->delete('/:foo' => {foo => 'bar'} => sub ($c) {...});
126         my $route = $r->delete('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
127         my $route = $r->delete('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
128
129       Generate Mojolicious::Routes::Route object matching only "DELETE"
130       requests, takes the same arguments as "any" (except for the HTTP
131       methods to match, which are implied). See Mojolicious::Guides::Tutorial
132       and Mojolicious::Guides::Routing for more information.
133
134         # Route with destination
135         $r->delete('/user')->to('user#remove');
136
137   find
138         my $route = $r->find('foo');
139
140       Find child route by name, custom names have precedence over
141       automatically generated ones.
142
143         # Change default parameters of a named route
144         $r->find('show_user')->to(foo => 'bar');
145
146   get
147         my $route = $r->get;
148         my $route = $r->get('/:foo');
149         my $route = $r->get('/:foo' => sub ($c) {...});
150         my $route = $r->get('/:foo' => sub ($c) {...} => 'name');
151         my $route = $r->get('/:foo' => {foo => 'bar'} => sub ($c) {...});
152         my $route = $r->get('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
153         my $route = $r->get('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
154
155       Generate Mojolicious::Routes::Route object matching only "GET"
156       requests, takes the same arguments as "any" (except for the HTTP
157       methods to match, which are implied). See Mojolicious::Guides::Tutorial
158       and Mojolicious::Guides::Routing for more information.
159
160         # Route with destination
161         $r->get('/user')->to('user#show');
162
163   has_custom_name
164         my $bool = $r->has_custom_name;
165
166       Check if this route has a custom name.
167
168   has_websocket
169         my $bool = $r->has_websocket;
170
171       Check if this route has a WebSocket ancestor and cache the result for
172       future checks.
173
174   is_endpoint
175         my $bool = $r->is_endpoint;
176
177       Check if this route qualifies as an endpoint.
178
179   is_reserved
180         my $bool = $r->is_reserved('controller');
181
182       Check if string is a reserved stash value.
183
184   is_websocket
185         my $bool = $r->is_websocket;
186
187       Check if this route is a WebSocket.
188
189   methods
190         my $methods = $r->methods;
191         $r          = $r->methods('GET');
192         $r          = $r->methods('GET', 'POST');
193         $r          = $r->methods(['GET', 'POST']);
194
195       Restrict HTTP methods this route is allowed to handle, defaults to no
196       restrictions.
197
198         # Route with two methods and destination
199         $r->any('/foo')->methods('GET', 'POST')->to('foo#bar');
200
201   name
202         my $name = $r->name;
203         $r       = $r->name('foo');
204
205       The name of this route, defaults to an automatically generated name
206       based on the route pattern. Note that the name "current" is reserved
207       for referring to the current route.
208
209         # Route with destination and custom name
210         $r->get('/user')->to('user#show')->name('show_user');
211
212   options
213         my $route = $r->options;
214         my $route = $r->options('/:foo');
215         my $route = $r->options('/:foo' => sub ($c) {...});
216         my $route = $r->options('/:foo' => sub ($c) {...} => 'name');
217         my $route = $r->options('/:foo' => {foo => 'bar'} => sub ($c) {...});
218         my $route = $r->options('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
219         my $route = $r->options('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
220
221       Generate Mojolicious::Routes::Route object matching only "OPTIONS"
222       requests, takes the same arguments as "any" (except for the HTTP
223       methods to match, which are implied). See Mojolicious::Guides::Tutorial
224       and Mojolicious::Guides::Routing for more information.
225
226         # Route with destination
227         $r->options('/user')->to('user#overview');
228
229   parse
230         $r = $r->parse('/user/:id');
231         $r = $r->parse('/user/:id', id => qr/\d+/);
232         $r = $r->parse(format => ['json', 'yaml']);
233
234       Parse pattern.
235
236   patch
237         my $route = $r->patch;
238         my $route = $r->patch('/:foo');
239         my $route = $r->patch('/:foo' => sub ($c) {...});
240         my $route = $r->patch('/:foo' => sub ($c) {...} => 'name');
241         my $route = $r->patch('/:foo' => {foo => 'bar'} => sub ($c) {...});
242         my $route = $r->patch('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
243         my $route = $r->patch('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
244
245       Generate Mojolicious::Routes::Route object matching only "PATCH"
246       requests, takes the same arguments as "any" (except for the HTTP
247       methods to match, which are implied). See Mojolicious::Guides::Tutorial
248       and Mojolicious::Guides::Routing for more information.
249
250         # Route with destination
251         $r->patch('/user')->to('user#update');
252
253   post
254         my $route = $r->post;
255         my $route = $r->post('/:foo');
256         my $route = $r->post('/:foo' => sub ($c) {...});
257         my $route = $r->post('/:foo' => sub ($c) {...} => 'name');
258         my $route = $r->post('/:foo' => {foo => 'bar'} => sub ($c) {...});
259         my $route = $r->post('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
260         my $route = $r->post('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
261
262       Generate Mojolicious::Routes::Route object matching only "POST"
263       requests, takes the same arguments as "any" (except for the HTTP
264       methods to match, which are implied). See Mojolicious::Guides::Tutorial
265       and Mojolicious::Guides::Routing for more information.
266
267         # Route with destination
268         $r->post('/user')->to('user#create');
269
270   put
271         my $route = $r->put;
272         my $route = $r->put('/:foo');
273         my $route = $r->put('/:foo' => sub ($c) {...});
274         my $route = $r->put('/:foo' => sub ($c) {...} => 'name');
275         my $route = $r->put('/:foo' => {foo => 'bar'} => sub ($c) {...});
276         my $route = $r->put('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
277         my $route = $r->put('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
278
279       Generate Mojolicious::Routes::Route object matching only "PUT"
280       requests, takes the same arguments as "any" (except for the HTTP
281       methods to match, which are implied). See Mojolicious::Guides::Tutorial
282       and Mojolicious::Guides::Routing for more information.
283
284         # Route with destination
285         $r->put('/user')->to('user#replace');
286
287   remove
288         $r = $r->remove;
289
290       Remove route from parent.
291
292         # Remove route completely
293         $r->find('foo')->remove;
294
295         # Reattach route to new parent
296         $r->any('/foo')->add_child($r->find('bar')->remove);
297
298   render
299         my $path = $r->render({foo => 'bar'});
300
301       Render route with parameters into a path.
302
303   root
304         my $root = $r->root;
305
306       The Mojolicious::Routes object this route is a descendant of.
307
308   requires
309         my $requires = $r->requires;
310         $r           = $r->requires(foo => 1);
311         $r           = $r->requires(foo => 1, bar => {baz => 'yada'});
312         $r           = $r->requires([foo => 1, bar => {baz => 'yada'}]);
313
314       Activate conditions for this route. Note that this automatically
315       disables the routing cache, since conditions are too complex for
316       caching.
317
318         # Route with condition and destination
319         $r->get('/foo')->requires(host => qr/mojolicious\.org/)->to('foo#bar');
320
321   suggested_method
322         my $method = $r->suggested_method;
323
324       Suggested HTTP method for reaching this route, "GET" and "POST" are
325       preferred.
326
327   to
328         my $defaults = $r->to;
329         $r           = $r->to(action => 'foo');
330         $r           = $r->to({action => 'foo'});
331         $r           = $r->to('controller#action');
332         $r           = $r->to('controller#action', foo => 'bar');
333         $r           = $r->to('controller#action', {foo => 'bar'});
334         $r           = $r->to(Mojolicious->new);
335         $r           = $r->to(Mojolicious->new, foo => 'bar');
336         $r           = $r->to(Mojolicious->new, {foo => 'bar'});
337         $r           = $r->to('MyApp');
338         $r           = $r->to('MyApp', foo => 'bar');
339         $r           = $r->to('MyApp', {foo => 'bar'});
340
341       Set default parameters for this route.
342
343   to_string
344         my $str = $r->to_string;
345
346       Stringify the whole route.
347
348   under
349         my $route = $r->under(sub ($c) {...});
350         my $route = $r->under('/:foo' => sub ($c) {...});
351         my $route = $r->under('/:foo' => {foo => 'bar'});
352         my $route = $r->under('/:foo' => [foo => qr/\w+/]);
353         my $route = $r->under('/:foo' => (agent => qr/Firefox/));
354         my $route = $r->under([format => ['json', 'yaml']]);
355
356       Generate Mojolicious::Routes::Route object for a nested route with its
357       own intermediate destination, takes the same arguments as "any" (except
358       for the HTTP methods to match, which are not available). See
359       Mojolicious::Guides::Tutorial and Mojolicious::Guides::Routing for more
360       information.
361
362         # Longer version
363         $r->any('/:foo' => sub ($c) {...})->inline(1);
364
365         # Intermediate destination and prefix shared between two routes
366         my $auth = $r->under('/user')->to('user#auth');
367         $auth->get('/show')->to('#show');
368         $auth->post('/create')->to('#create');
369
370   websocket
371         my $route = $r->websocket;
372         my $route = $r->websocket('/:foo');
373         my $route = $r->websocket('/:foo' => sub ($c) {...});
374         my $route = $r->websocket('/:foo' => sub ($c) {...} => 'name');
375         my $route = $r->websocket('/:foo' => {foo => 'bar'} => sub ($c) {...});
376         my $route = $r->websocket('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
377         my $route = $r->websocket('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
378
379       Generate Mojolicious::Routes::Route object matching only WebSocket
380       handshakes, takes the same arguments as "any" (except for the HTTP
381       methods to match, which are implied). See Mojolicious::Guides::Tutorial
382       and Mojolicious::Guides::Routing for more information.
383
384         # Route with destination
385         $r->websocket('/echo')->to('example#echo');
386

SHORTCUTS

388       In addition to the "ATTRIBUTES" and "METHODS" above you can also call
389       shortcuts provided by "root" on Mojolicious::Routes::Route objects.
390
391         # Add a "firefox" shortcut
392         $r->root->add_shortcut(firefox => sub ($r, $path) {
393           $r->get($path, agent => qr/Firefox/);
394         });
395
396         # Use "firefox" shortcut to generate routes
397         $r->firefox('/welcome')->to('firefox#welcome');
398         $r->firefox('/bye')->to('firefox#bye');
399

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

SHORTCUTS

SEE ALSO