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 {...});
70         my $route = $r->any('/:foo' => sub {...} => 'name');
71         my $route = $r->any('/:foo' => {foo => 'bar'} => sub {...});
72         my $route = $r->any('/:foo' => [foo => qr/\w+/] => sub {...});
73         my $route = $r->any('/:foo' => (agent => qr/Firefox/) => sub {...});
74         my $route = $r->any(['GET', 'POST'] => '/:foo' => sub {...});
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 {
114           my $c = shift;
115           $c->render(text => 'Hello World!');
116         });
117
118       See Mojolicious::Guides::Tutorial and Mojolicious::Guides::Routing for
119       more information.
120
121   delete
122         my $route = $r->delete;
123         my $route = $r->delete('/:foo');
124         my $route = $r->delete('/:foo' => sub {...});
125         my $route = $r->delete('/:foo' => sub {...} => 'name');
126         my $route = $r->delete('/:foo' => {foo => 'bar'} => sub {...});
127         my $route = $r->delete('/:foo' => [foo => qr/\w+/] => sub {...});
128         my $route = $r->delete('/:foo' => (agent => qr/Firefox/) => sub {...});
129
130       Generate Mojolicious::Routes::Route object matching only "DELETE"
131       requests, takes the same arguments as "any" (except for the HTTP
132       methods to match, which are implied). See Mojolicious::Guides::Tutorial
133       and Mojolicious::Guides::Routing for more information.
134
135         # Route with destination
136         $r->delete('/user')->to('user#remove');
137
138   detour
139         $r = $r->detour(action => 'foo');
140         $r = $r->detour('controller#action');
141         $r = $r->detour(Mojolicious->new, foo => 'bar');
142         $r = $r->detour('MyApp', {foo => 'bar'});
143
144       Set default parameters for this route and allow partial matching to
145       simplify application embedding, takes the same arguments as "to".
146
147   find
148         my $route = $r->find('foo');
149
150       Find child route by name, custom names have precedence over
151       automatically generated ones.
152
153         # Change default parameters of a named route
154         $r->find('show_user')->to(foo => 'bar');
155
156   get
157         my $route = $r->get;
158         my $route = $r->get('/:foo');
159         my $route = $r->get('/:foo' => sub {...});
160         my $route = $r->get('/:foo' => sub {...} => 'name');
161         my $route = $r->get('/:foo' => {foo => 'bar'} => sub {...});
162         my $route = $r->get('/:foo' => [foo => qr/\w+/] => sub {...});
163         my $route = $r->get('/:foo' => (agent => qr/Firefox/) => sub {...});
164
165       Generate Mojolicious::Routes::Route object matching only "GET"
166       requests, takes the same arguments as "any" (except for the HTTP
167       methods to match, which are implied). See Mojolicious::Guides::Tutorial
168       and Mojolicious::Guides::Routing for more information.
169
170         # Route with destination
171         $r->get('/user')->to('user#show');
172
173   has_custom_name
174         my $bool = $r->has_custom_name;
175
176       Check if this route has a custom name.
177
178   has_websocket
179         my $bool = $r->has_websocket;
180
181       Check if this route has a WebSocket ancestor and cache the result for
182       future checks.
183
184   is_endpoint
185         my $bool = $r->is_endpoint;
186
187       Check if this route qualifies as an endpoint.
188
189   is_websocket
190         my $bool = $r->is_websocket;
191
192       Check if this route is a WebSocket.
193
194   name
195         my $name = $r->name;
196         $r       = $r->name('foo');
197
198       The name of this route, defaults to an automatically generated name
199       based on the route pattern. Note that the name "current" is reserved
200       for referring to the current route.
201
202         # Route with destination and custom name
203         $r->get('/user')->to('user#show')->name('show_user');
204
205   options
206         my $route = $r->options;
207         my $route = $r->options('/:foo');
208         my $route = $r->options('/:foo' => sub {...});
209         my $route = $r->options('/:foo' => sub {...} => 'name');
210         my $route = $r->options('/:foo' => {foo => 'bar'} => sub {...});
211         my $route = $r->options('/:foo' => [foo => qr/\w+/] => sub {...});
212         my $route = $r->options('/:foo' => (agent => qr/Firefox/) => sub {...});
213
214       Generate Mojolicious::Routes::Route object matching only "OPTIONS"
215       requests, takes the same arguments as "any" (except for the HTTP
216       methods to match, which are implied). See Mojolicious::Guides::Tutorial
217       and Mojolicious::Guides::Routing for more information.
218
219         # Route with destination
220         $r->options('/user')->to('user#overview');
221
222   over
223         my $over = $r->over;
224         $r       = $r->over(foo => 1);
225         $r       = $r->over(foo => 1, bar => {baz => 'yada'});
226         $r       = $r->over([foo => 1, bar => {baz => 'yada'}]);
227
228       Activate conditions for this route. Note that this automatically
229       disables the routing cache, since conditions are too complex for
230       caching.
231
232         # Route with condition and destination
233         $r->get('/foo')->over(host => qr/mojolicious\.org/)->to('foo#bar');
234
235   parse
236         $r = $r->parse('/:action');
237         $r = $r->parse('/:action', action => qr/\w+/);
238         $r = $r->parse(format => 0);
239
240       Parse pattern.
241
242   patch
243         my $route = $r->patch;
244         my $route = $r->patch('/:foo');
245         my $route = $r->patch('/:foo' => sub {...});
246         my $route = $r->patch('/:foo' => sub {...} => 'name');
247         my $route = $r->patch('/:foo' => {foo => 'bar'} => sub {...});
248         my $route = $r->patch('/:foo' => [foo => qr/\w+/] => sub {...});
249         my $route = $r->patch('/:foo' => (agent => qr/Firefox/) => sub {...});
250
251       Generate Mojolicious::Routes::Route object matching only "PATCH"
252       requests, takes the same arguments as "any" (except for the HTTP
253       methods to match, which are implied). See Mojolicious::Guides::Tutorial
254       and Mojolicious::Guides::Routing for more information.
255
256         # Route with destination
257         $r->patch('/user')->to('user#update');
258
259   post
260         my $route = $r->post;
261         my $route = $r->post('/:foo');
262         my $route = $r->post('/:foo' => sub {...});
263         my $route = $r->post('/:foo' => sub {...} => 'name');
264         my $route = $r->post('/:foo' => {foo => 'bar'} => sub {...});
265         my $route = $r->post('/:foo' => [foo => qr/\w+/] => sub {...});
266         my $route = $r->post('/:foo' => (agent => qr/Firefox/) => sub {...});
267
268       Generate Mojolicious::Routes::Route object matching only "POST"
269       requests, takes the same arguments as "any" (except for the HTTP
270       methods to match, which are implied). See Mojolicious::Guides::Tutorial
271       and Mojolicious::Guides::Routing for more information.
272
273         # Route with destination
274         $r->post('/user')->to('user#create');
275
276   put
277         my $route = $r->put;
278         my $route = $r->put('/:foo');
279         my $route = $r->put('/:foo' => sub {...});
280         my $route = $r->put('/:foo' => sub {...} => 'name');
281         my $route = $r->put('/:foo' => {foo => 'bar'} => sub {...});
282         my $route = $r->put('/:foo' => [foo => qr/\w+/] => sub {...});
283         my $route = $r->put('/:foo' => (agent => qr/Firefox/) => sub {...});
284
285       Generate Mojolicious::Routes::Route object matching only "PUT"
286       requests, takes the same arguments as "any" (except for the HTTP
287       methods to match, which are implied). See Mojolicious::Guides::Tutorial
288       and Mojolicious::Guides::Routing for more information.
289
290         # Route with destination
291         $r->put('/user')->to('user#replace');
292
293   remove
294         $r = $r->remove;
295
296       Remove route from parent.
297
298         # Remove route completely
299         $r->find('foo')->remove;
300
301         # Reattach route to new parent
302         $r->route('/foo')->add_child($r->find('bar')->remove);
303
304   render
305         my $path = $r->render({foo => 'bar'});
306
307       Render route with parameters into a path.
308
309   root
310         my $root = $r->root;
311
312       The Mojolicious::Routes object this route is a descendant of.
313
314   route
315         my $route = $r->route;
316         my $route = $r->route('/:action');
317         my $route = $r->route('/:action', action => qr/\w+/);
318         my $route = $r->route(format => 0);
319
320       Low-level generator for routes matching all HTTP request methods,
321       returns a Mojolicious::Routes::Route object.
322
323   suggested_method
324         my $method = $r->suggested_method;
325
326       Suggested HTTP method for reaching this route, "GET" and "POST" are
327       preferred.
328
329   to
330         my $defaults = $r->to;
331         $r           = $r->to(action => 'foo');
332         $r           = $r->to({action => 'foo'});
333         $r           = $r->to('controller#action');
334         $r           = $r->to('controller#action', foo => 'bar');
335         $r           = $r->to('controller#action', {foo => 'bar'});
336         $r           = $r->to(Mojolicious->new);
337         $r           = $r->to(Mojolicious->new, foo => 'bar');
338         $r           = $r->to(Mojolicious->new, {foo => 'bar'});
339         $r           = $r->to('MyApp');
340         $r           = $r->to('MyApp', foo => 'bar');
341         $r           = $r->to('MyApp', {foo => 'bar'});
342
343       Set default parameters for this route.
344
345   to_string
346         my $str = $r->to_string;
347
348       Stringify the whole route.
349
350   under
351         my $route = $r->under(sub {...});
352         my $route = $r->under('/:foo' => sub {...});
353         my $route = $r->under('/:foo' => {foo => 'bar'});
354         my $route = $r->under('/:foo' => [foo => qr/\w+/]);
355         my $route = $r->under('/:foo' => (agent => qr/Firefox/));
356         my $route = $r->under([format => 0]);
357
358       Generate Mojolicious::Routes::Route object for a nested route with its
359       own intermediate destination, takes the same arguments as "any" (except
360       for the HTTP methods to match, which are not available). See
361       Mojolicious::Guides::Tutorial and Mojolicious::Guides::Routing for more
362       information.
363
364         # Longer version
365         $r->any('/:foo' => sub {...})->inline(1);
366
367         # Intermediate destination and prefix shared between two routes
368         my $auth = $r->under('/user')->to('user#auth');
369         $auth->get('/show')->to('#show');
370         $auth->post('/create')->to('#create');
371
372   via
373         my $methods = $r->via;
374         $r          = $r->via('GET');
375         $r          = $r->via('GET', 'POST');
376         $r          = $r->via(['GET', 'POST']);
377
378       Restrict HTTP methods this route is allowed to handle, defaults to no
379       restrictions.
380
381         # Route with two methods and destination
382         $r->route('/foo')->via('GET', 'POST')->to('foo#bar');
383
384   websocket
385         my $route = $r->websocket;
386         my $route = $r->websocket('/:foo');
387         my $route = $r->websocket('/:foo' => sub {...});
388         my $route = $r->websocket('/:foo' => sub {...} => 'name');
389         my $route = $r->websocket('/:foo' => {foo => 'bar'} => sub {...});
390         my $route = $r->websocket('/:foo' => [foo => qr/\w+/] => sub {...});
391         my $route = $r->websocket('/:foo' => (agent => qr/Firefox/) => sub {...});
392
393       Generate Mojolicious::Routes::Route object matching only WebSocket
394       handshakes, takes the same arguments as "any" (except for the HTTP
395       methods to match, which are implied). See Mojolicious::Guides::Tutorial
396       and Mojolicious::Guides::Routing for more information.
397
398         # Route with destination
399         $r->websocket('/echo')->to('example#echo');
400

SHORTCUTS

402       In addition to the "ATTRIBUTES" and "METHODS" above you can also call
403       shortcuts provided by "root" on Mojolicious::Routes::Route objects.
404
405         # Add a "firefox" shortcut
406         $r->root->add_shortcut(firefox => sub {
407           my ($r, $path) = @_;
408           $r->get($path, agent => qr/Firefox/);
409         });
410
411         # Use "firefox" shortcut to generate routes
412         $r->firefox('/welcome')->to('firefox#welcome');
413         $r->firefox('/bye')->to('firefox#bye');
414

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

SHORTCUTS

SEE ALSO