The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mojolicious-2.58
River stage four • 943 direct dependents • 1041 total dependents
495 ++
/ Mojolicious::Routes

NAME

Mojolicious::Routes - Always find your destination with routes

SYNOPSIS

  use Mojolicious::Routes;

  # New routes tree
  my $r = Mojolicious::Routes->new;

  # Normal route matching "/articles" with parameters "controller" and
  # "action"
  $r->route('/articles')->to(controller => 'article', action => 'list');

  # Route with a placeholder matching everything but "/" and "."
  $r->route('/:controller')->to(action => 'list');

  # Route with a placeholder and regex constraint
  $r->route('/articles/:id', id => qr/\d+/)
    ->to(controller => 'article', action => 'view');

  # Route with an optional parameter "year"
  $r->route('/archive/:year')
    ->to(controller => 'archive', action => 'list', year => undef);

  # Nested route for two actions sharing the same "controller" parameter
  my $books = $r->route('/books/:id')->to(controller => 'book');
  $books->route('/edit')->to(action => 'edit');
  $books->route('/delete')->to(action => 'delete');

  # Bridges can be used to chain multiple routes
  $r->bridge->to(controller => 'foo', action =>'auth')
    ->route('/blog')->to(action => 'list');

  # Waypoints are similar to bridges and nested routes but can also match
  # if they are not the actual endpoint of the whole route
  my $b = $r->waypoint('/books')->to(controller => 'books', action => 'list');
  $b->route('/:id', id => qr/\d+/)->to(action => 'view');

  # Simplified Mojolicious::Lite style route generation is also possible
  $r->get('/')->to(controller => 'blog', action => 'welcome');
  my $blog = $r->under('/blog');
  $blog->post('/list')->to('blog#list');
  $blog->get(sub { shift->render(text => 'Go away!') });

DESCRIPTION

Mojolicious::Routes is the core of the Mojolicious web framework. See Mojolicious::Guides::Routing for more.

ATTRIBUTES

Mojolicious::Routes implements the following attributes.

block

  my $block = $r->block;
  $r        = $r->block(1);

Allow this route to match even if it's not an endpoint, used for waypoints.

children

  my $children = $r->children;
  $r           = $r->children([Mojolicious::Routes->new]);

The children of this routes object, used for nesting routes.

cache

  my $cache = $r->cache;
  $r        = $r->cache(Mojo::Cache->new);

Routing cache, defaults to a Mojo::Cache object. Note that this attribute is EXPERIMENTAL and might change without warning!

conditions

  my $conditions  = $r->conditions;
  $r              = $r->conditions([foo => qr/\w+/]);

Contains condition parameters for this route, used for over.

controller_base_class

  my $base = $r->controller_base_class;
  $r       = $r->controller_base_class('Mojolicious::Controller');

Base class used to identify controllers, defaults to Mojolicious::Controller.

dictionary

  my $dictionary = $r->dictionary;
  $r             = $r->dictionary({foo => sub {...}});

Contains all available conditions for this route.

hidden

  my $hidden = $r->hidden;
  $r         = $r->hidden([qw/new attr tx render req res stash/]);

Controller methods and attributes that are hidden from routes.

inline

  my $inline = $r->inline;
  $r         = $r->inline(1);

Allow bridge semantics for this route.

namespace

  my $namespace = $r->namespace;
  $r            = $r->namespace('Foo::Bar::Controller');

Namespace used by dispatch to search for controllers.

parent

  my $parent = $r->parent;
  $r         = $r->parent(Mojolicious::Routes->new);

The parent of this route, used for nesting routes.

partial

  my $partial = $r->partial;
  $r          = $r->partial(1);

Route has no specific end, remaining characters will be captured in path.

pattern

  my $pattern = $r->pattern;
  $r          = $r->pattern(Mojolicious::Routes::Pattern->new);

Pattern for this route, defaults to a Mojolicious::Routes::Pattern object.

shortcuts

  my $shortcuts = $r->shortcuts;
  $r            = $r->shortcuts({foo => sub {...}});

Contains all additional route shortcuts available for this route.

METHODS

Mojolicious::Routes inherits all methods from Mojo::Base and implements the following ones.

new

  my $r = Mojolicious::Routes->new;
  my $r = Mojolicious::Routes->new('/:controller/:action');

Construct a new route object.

add_child

  $r = $r->add_child(Mojolicious::Route->new);

Add a new child to this route.

add_condition

  $r = $r->add_condition(foo => sub {...});

Add a new condition for this route.

add_shortcut

  $r = $r->add_shortcut(foo => sub {...});

Add a new shortcut for this route.

any

  my $route = $route->any('/:foo' => sub {...});
  my $route = $route->any([qw/get post/] => '/:foo' => sub {...});

Generate route matching any of the listed HTTP request methods or all. See also the Mojolicious::Lite tutorial for more argument variations.

auto_render

  $r->auto_render(Mojolicious::Controller->new);

Automatic rendering.

bridge

  my $bridge = $r->bridge;
  my $bridge = $r->bridge('/:controller/:action');

Add a new bridge to this route as a nested child.

delete

  my $route = $route->delete('/:foo' => sub {...});

Generate route matching only DELETE requests. See also the Mojolicious::Lite tutorial for more argument variations.

detour

  $r = $r->detour(action => 'foo');
  $r = $r->detour({action => 'foo'});
  $r = $r->detour('controller#action');
  $r = $r->detour('controller#action', foo => 'bar');
  $r = $r->detour('controller#action', {foo => 'bar'});
  $r = $r->detour($app);
  $r = $r->detour($app, foo => 'bar');
  $r = $r->detour($app, {foo => 'bar'});
  $r = $r->detour('MyApp');
  $r = $r->detour('MyApp', foo => 'bar');
  $r = $r->detour('MyApp', {foo => 'bar'});

Set default parameters for this route and allow partial matching to simplify application embedding.

dispatch

  my $success = $r->dispatch(Mojolicious::Controller->new);

Match routes and dispatch.

get

  my $route = $route->get('/:foo' => sub {...});

Generate route matching only GET requests. See also the Mojolicious::Lite tutorial for more argument variations.

has_conditions

  my $success = $r->has_conditions;

Returns true if this route contains conditions. Note that this method is EXPERIMENTAL and might change without warning!

has_custom_name

  my $success = $r->has_custom_name;

Returns true if this route has a custom user defined name. Note that this method is EXPERIMENTAL and might change without warning!

has_websocket

  my $success = $r->has_websocket;

Returns true if this route has a WebSocket ancestor. Note that this method is EXPERIMENTAL and might change without warning!

hide

  $r = $r->hide('new');

Hide controller method or attribute from routes.

is_endpoint

  my $success = $r->is_endpoint;

Returns true if this route qualifies as an endpoint.

is_websocket

  my $success = $r->is_websocket;

Returns true if this route is a WebSocket. Note that this method is EXPERIMENTAL and might change without warning!

name

  my $name = $r->name;
  $r       = $r->name('foo');

The name of this route, defaults to an automatically generated name based on the route pattern. Note that the name current is reserved for refering to the current route.

over

  $r = $r->over(foo => qr/\w+/);

Apply condition parameters to this route and disable routing cache.

parse

  $r = $r->parse('/:controller/:action');

Parse a pattern.

patch

  my $route = $route->patch('/:foo' => sub {...});

Generate route matching only PATCH requests. See also the Mojolicious::Lite tutorial for more argument variations.

post

  my $route = $route->post('/:foo' => sub {...});

Generate route matching only POST requests. See also the Mojolicious::Lite tutorial for more argument variations.

put

  my $route = $route->put('/:foo' => sub {...});

Generate route matching only PUT requests. See also the Mojolicious::Lite tutorial for more argument variations.

render

  my $path = $r->render($path);
  my $path = $r->render($path, {foo => 'bar'});

Render route with parameters into a path.

route

  my $route = $r->route('/:c/:a', a => qr/\w+/);

Add a new nested child to this route.

to

  my $to  = $r->to;
  $r = $r->to(action => 'foo');
  $r = $r->to({action => 'foo'});
  $r = $r->to('controller#action');
  $r = $r->to('controller#action', foo => 'bar');
  $r = $r->to('controller#action', {foo => 'bar'});
  $r = $r->to($app);
  $r = $r->to($app, foo => 'bar');
  $r = $r->to($app, {foo => 'bar'});
  $r = $r->to('MyApp');
  $r = $r->to('MyApp', foo => 'bar');
  $r = $r->to('MyApp', {foo => 'bar'});

Set default parameters for this route.

to_string

  my $string = $r->to_string;

Stringifies the whole route.

under

  my $route = $r->under(sub {...});
  my $route = $r->under('/:foo');

Generate bridges. See also the Mojolicious::Lite tutorial for more argument variations.

via

  my $methods = $r->via;
  $r          = $r->via('GET');
  $r          = $r->via(qw/GET POST/);
  $r          = $r->via([qw/GET POST/]);

Restrict HTTP methods this route is allowed to handle, defaults to no restrictions.

waypoint

  my $r = $r->waypoint('/:c/:a', a => qr/\w+/);

Add a waypoint to this route as nested child.

websocket

  my $websocket = $r->websocket('/:foo' => sub {...});

Generate route matching only WebSocket handshakes. See also the Mojolicious::Lite tutorial for more argument variations. Note that this method is EXPERIMENTAL and might change without warning!

SHORTCUTS

In addition to the attributes and methods above you can also call shortcuts on Mojolicious::Routes objects.

  $r->add_shortcut(firefox => sub {
    my ($r, $path) = @_;
    $r->get($path, agent => qr/Firefox/);
  });

  $r->firefox('/welcome')->to('firefox#welcome');
  $r->firefox('/bye')->to('firefox#bye);

SEE ALSO

Mojolicious, Mojolicious::Guides, http://mojolicio.us.