The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Nile-0.13
River stage zero No dependents
2 ++
/ Nile::Router

NAME

Nile::Router - URL route manager.

SYNOPSIS

        # load routes file from the path/route folder. default file extension is xml.
        $self->me->router->load("route");
        
        # find route action and information if exist in the routes file.
        my ($action, $args, $uri, $query) = $self->me->router->match($route, $request_method);
        
        # or as hash ref
        my $route = $self->me->router->match($route, $request_method);
        $route->{action}, $route->{args}, $route->{query}, $route->{uri}

DESCRIPTION

Nile::Router - URL route manager.

This module uses Router::Generic module to manage the routing table.

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, see Router::Generic for details about this. 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.

router()

        $self->me->router->router;

This is a Router::Generic object used internally.

load()

        # load routes file. default file extension is xml. load route.xml file.
        $self->me->router->load("route");
        
        # add another routes file. load and add the file blog.xml file.
        $self->me->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 information if exist in the routes file.
        my ($action, $args, $uri, $query) = $self->me->router->match($route, $request_method);
        
        # or as hash ref
        my $route = $self->me->router->match($route, $request_method);
        $route->{action}, $route->{args}, $route->{query}, $route->{uri}

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

add_route()

        # add new route information to the router object
        $self->me->router->  $router->add_route(
                                                        name  => "blogview",
                                                        path  => "blog/view/{id:\d+}",
                                                        target  => "/Blog/Blog/view",
                                                        method  => "*", # get, post, *, put, delete
                                                        defaults  => {
                                                                        id => 1
                                                                }
                                                );

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.

uri_for()

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

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

route_for()

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

Returns the route matching the path and method.

url_decode()

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

url_encode()

        my $encoded_url = $self->me->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.

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.