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_websocket
180         my $bool = $r->is_websocket;
181
182       Check if this route is a WebSocket.
183
184   methods
185         my $methods = $r->methods;
186         $r          = $r->methods('GET');
187         $r          = $r->methods('GET', 'POST');
188         $r          = $r->methods(['GET', 'POST']);
189
190       Restrict HTTP methods this route is allowed to handle, defaults to no
191       restrictions.
192
193         # Route with two methods and destination
194         $r->any('/foo')->methods('GET', 'POST')->to('foo#bar');
195
196   name
197         my $name = $r->name;
198         $r       = $r->name('foo');
199
200       The name of this route, defaults to an automatically generated name
201       based on the route pattern. Note that the name "current" is reserved
202       for referring to the current route.
203
204         # Route with destination and custom name
205         $r->get('/user')->to('user#show')->name('show_user');
206
207   options
208         my $route = $r->options;
209         my $route = $r->options('/:foo');
210         my $route = $r->options('/:foo' => sub ($c) {...});
211         my $route = $r->options('/:foo' => sub ($c) {...} => 'name');
212         my $route = $r->options('/:foo' => {foo => 'bar'} => sub ($c) {...});
213         my $route = $r->options('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
214         my $route = $r->options('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
215
216       Generate Mojolicious::Routes::Route object matching only "OPTIONS"
217       requests, takes the same arguments as "any" (except for the HTTP
218       methods to match, which are implied). See Mojolicious::Guides::Tutorial
219       and Mojolicious::Guides::Routing for more information.
220
221         # Route with destination
222         $r->options('/user')->to('user#overview');
223
224   parse
225         $r = $r->parse('/user/:id');
226         $r = $r->parse('/user/:id', id => qr/\d+/);
227         $r = $r->parse(format => 0);
228
229       Parse pattern.
230
231   patch
232         my $route = $r->patch;
233         my $route = $r->patch('/:foo');
234         my $route = $r->patch('/:foo' => sub ($c) {...});
235         my $route = $r->patch('/:foo' => sub ($c) {...} => 'name');
236         my $route = $r->patch('/:foo' => {foo => 'bar'} => sub ($c) {...});
237         my $route = $r->patch('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
238         my $route = $r->patch('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
239
240       Generate Mojolicious::Routes::Route object matching only "PATCH"
241       requests, takes the same arguments as "any" (except for the HTTP
242       methods to match, which are implied). See Mojolicious::Guides::Tutorial
243       and Mojolicious::Guides::Routing for more information.
244
245         # Route with destination
246         $r->patch('/user')->to('user#update');
247
248   post
249         my $route = $r->post;
250         my $route = $r->post('/:foo');
251         my $route = $r->post('/:foo' => sub ($c) {...});
252         my $route = $r->post('/:foo' => sub ($c) {...} => 'name');
253         my $route = $r->post('/:foo' => {foo => 'bar'} => sub ($c) {...});
254         my $route = $r->post('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
255         my $route = $r->post('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
256
257       Generate Mojolicious::Routes::Route object matching only "POST"
258       requests, takes the same arguments as "any" (except for the HTTP
259       methods to match, which are implied). See Mojolicious::Guides::Tutorial
260       and Mojolicious::Guides::Routing for more information.
261
262         # Route with destination
263         $r->post('/user')->to('user#create');
264
265   put
266         my $route = $r->put;
267         my $route = $r->put('/:foo');
268         my $route = $r->put('/:foo' => sub ($c) {...});
269         my $route = $r->put('/:foo' => sub ($c) {...} => 'name');
270         my $route = $r->put('/:foo' => {foo => 'bar'} => sub ($c) {...});
271         my $route = $r->put('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
272         my $route = $r->put('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
273
274       Generate Mojolicious::Routes::Route object matching only "PUT"
275       requests, takes the same arguments as "any" (except for the HTTP
276       methods to match, which are implied). See Mojolicious::Guides::Tutorial
277       and Mojolicious::Guides::Routing for more information.
278
279         # Route with destination
280         $r->put('/user')->to('user#replace');
281
282   remove
283         $r = $r->remove;
284
285       Remove route from parent.
286
287         # Remove route completely
288         $r->find('foo')->remove;
289
290         # Reattach route to new parent
291         $r->any('/foo')->add_child($r->find('bar')->remove);
292
293   render
294         my $path = $r->render({foo => 'bar'});
295
296       Render route with parameters into a path.
297
298   root
299         my $root = $r->root;
300
301       The Mojolicious::Routes object this route is a descendant of.
302
303   requires
304         my $requires = $r->requires;
305         $r           = $r->requires(foo => 1);
306         $r           = $r->requires(foo => 1, bar => {baz => 'yada'});
307         $r           = $r->requires([foo => 1, bar => {baz => 'yada'}]);
308
309       Activate conditions for this route. Note that this automatically
310       disables the routing cache, since conditions are too complex for
311       caching.
312
313         # Route with condition and destination
314         $r->get('/foo')->requires(host => qr/mojolicious\.org/)->to('foo#bar');
315
316   suggested_method
317         my $method = $r->suggested_method;
318
319       Suggested HTTP method for reaching this route, "GET" and "POST" are
320       preferred.
321
322   to
323         my $defaults = $r->to;
324         $r           = $r->to(action => 'foo');
325         $r           = $r->to({action => 'foo'});
326         $r           = $r->to('controller#action');
327         $r           = $r->to('controller#action', foo => 'bar');
328         $r           = $r->to('controller#action', {foo => 'bar'});
329         $r           = $r->to(Mojolicious->new);
330         $r           = $r->to(Mojolicious->new, foo => 'bar');
331         $r           = $r->to(Mojolicious->new, {foo => 'bar'});
332         $r           = $r->to('MyApp');
333         $r           = $r->to('MyApp', foo => 'bar');
334         $r           = $r->to('MyApp', {foo => 'bar'});
335
336       Set default parameters for this route.
337
338   to_string
339         my $str = $r->to_string;
340
341       Stringify the whole route.
342
343   under
344         my $route = $r->under(sub ($c) {...});
345         my $route = $r->under('/:foo' => sub ($c) {...});
346         my $route = $r->under('/:foo' => {foo => 'bar'});
347         my $route = $r->under('/:foo' => [foo => qr/\w+/]);
348         my $route = $r->under('/:foo' => (agent => qr/Firefox/));
349         my $route = $r->under([format => 0]);
350
351       Generate Mojolicious::Routes::Route object for a nested route with its
352       own intermediate destination, takes the same arguments as "any" (except
353       for the HTTP methods to match, which are not available). See
354       Mojolicious::Guides::Tutorial and Mojolicious::Guides::Routing for more
355       information.
356
357         # Longer version
358         $r->any('/:foo' => sub ($c) {...})->inline(1);
359
360         # Intermediate destination and prefix shared between two routes
361         my $auth = $r->under('/user')->to('user#auth');
362         $auth->get('/show')->to('#show');
363         $auth->post('/create')->to('#create');
364
365   websocket
366         my $route = $r->websocket;
367         my $route = $r->websocket('/:foo');
368         my $route = $r->websocket('/:foo' => sub ($c) {...});
369         my $route = $r->websocket('/:foo' => sub ($c) {...} => 'name');
370         my $route = $r->websocket('/:foo' => {foo => 'bar'} => sub ($c) {...});
371         my $route = $r->websocket('/:foo' => [foo => qr/\w+/] => sub ($c) {...});
372         my $route = $r->websocket('/:foo' => (agent => qr/Firefox/) => sub ($c) {...});
373
374       Generate Mojolicious::Routes::Route object matching only WebSocket
375       handshakes, takes the same arguments as "any" (except for the HTTP
376       methods to match, which are implied). See Mojolicious::Guides::Tutorial
377       and Mojolicious::Guides::Routing for more information.
378
379         # Route with destination
380         $r->websocket('/echo')->to('example#echo');
381

SHORTCUTS

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

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

SHORTCUTS

SEE ALSO