/ 
Nile-0.55
River stage zero No dependents
/ Nile::Router

NAME

Nile::Router - URL route manager.

SYNOPSIS

# get router object
$router = $app->router;

# load routes file from the path/route folder. default file extension is xml.
$router->load("route");

# find route action and its information, result is hash ref
my $match = $router->match($route, $request_method);
say $match->{action},
    $match->{args},
    $match->{query},
    $match->{uri},
    $match->{code},
    $match->{route};

my $match = $router->match("/news/world/egypt/politics/2014/07/24/1579279", "get");
my $match = $router->match("/blog/computer/software/article_name");
my $match = $router->match($route, $request_method);

# add new route information to the router object
$router->add_route(
    name  => "blogview",
    path  => "blog/view/{id:\d+}",
    target  => "/Blog/Blog/view", # can be a code ref like sub{...}
    method  => "*", # get, post, put, patch, delete, options, head, ajax, *
    defaults  => {
            id => 1
        },
    attributes => "capture", # undef or "capture" for inline actions capture
);

DESCRIPTION

Nile::Router - URL route manager.

ROUTES FILES

Routes are stored in a special xml files in the application folder named route. Below is a sample route.xml file.

<?xml version="1.0" encoding="UTF-8" ?>

<register route="/register" action="Accounts/Register/create" method="get" defaults="year=1900|month=1|day=23" />
<post route="/blog/post/{cid:\d+}/{id:\d+}" action="Blog/Article/post" method="post" />
<browse route="/blog/{id:\d+}" action="Blog/Article/browse" method="get" />
<view route="/blog/view/{id:\d+}" action="Blog/Article/view" method="get" />
<edit route="/blog/edit/{id:\d+}" action="Blog/Article/edit" method="get" />

Each route entry in the routes file has the following format:

<name route="/blog" action="Plugin/Controller/Action" method="get" defaults="k1=v1|k2=v2..." />

The following are the components of the route tag: The route 'name', this must be unique name for the route. The url 'route' or path that should match. The 'action' or target which should be executed if route matched the path. The 'method' is optional and if provided will only match the route if request method matched it. Empty or '*' will match all. The 'defaults' is optional and can be used to provide a default values for the route params if not exist. These params if exist will be added to the request params in the request object.

Routes are loaded and matched in the same order they exist in the file, the sort order is kept the same.

load()

# load routes file. default file extension is xml. load route.xml file.
$router->load("route");

# add another routes file. load and add the file blog.xml file.
$router->load("blog");

Loads and adds routes files. Routes files are XML files with specific tags. Everytime you load a route file it will be added to the routes and does not clear the previously loaded files unless you call the clear method. This method can be chained.

match()

# find route action and its information, result is hash ref
my $match = $router->match($route, $request_method);
say $match->{action},
    $match->{args},
    $match->{query},
    $match->{uri},
    $match->{code},
    $match->{route};

Match routes from the loaded routes files. If route matched returns route target or action, default arguments if provided, and uri and query information.

uri_for()

my $route = $router->uri_for($route_name, \%params);

Returns the uri for a given route with the provided params.

route_for()

my $route = $router->route_for($path, [$method]);

Returns the route matching the path and method.

add_route()

# add new route information to the router object
$router->add_route(
    name  => "blogview",
    path  => "blog/view/{id:\d+}",
    target  => "/Blog/Blog/view", # can be a code ref like sub{...}
    method  => "*", # get, post, put, patch, delete, options, head, ajax, *
    defaults  => {
            id => 1
        },
    attributes => "capture", # undef or "capture" for inline actions capture
);

This method adds a new route information to the routing table. Routes must be unique, so you can't have two routes that both look like /blog/:id for example. An exception will be thrown if an attempt is made to add a route that already exists. If route name is empty, a custom route name in the form __ROUTE__[number] will be used.

url_decode()

my $decode_url = $router->url_decode($url);

url_encode()

my $encoded_url = $router->url_encode($url);

Bugs

This project is available on github at https://github.com/mewsoft/Nile.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Nile.

SOURCE

Source repository is at https://github.com/mewsoft/Nile.

SEE ALSO

See Nile for details about the complete framework.

AUTHOR

Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org> Website: http://www.mewsoft.com

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy احمد امين الششتاوى mewsoft@cpan.org, support@mewsoft.com, https://github.com/mewsoft/Nile, http://www.mewsoft.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.