/ 
ASP4x-Router-0.007
River stage zero No dependents
/ ASP4x::Router

NAME

ASP4x::Router - URL Routing for your ASP4 web application.

SYNOPSIS

httpd.conf

<Perl>
  push @INC, '/path/to/yoursite.com/lib';
</Perl>

PerlModule ASP4x::Router

...

<VirtualHost *:80>
...
  PerlTransHandler ASP4x::Router
...
</VirtualHost>

asp4-config.json

...
"web": {
  ...
  "request_filters": [
    ...
    {
      "uri_match": "/.*",
      "class":     "ASP4x::Router"
    }
    ...
  ]
  ...
  "routes": [
    {
      "name":   "CreatePage",
      "path":   "/main/:type/create",
      "target": "/pages/create.asp",
      "method": "GET"
    },
    {
      "name":   "Create",
      "path":   "/main/:type/create",
      "target": "/handlers/dev.create",
      "method": "POST"
    },
    {
      "name":   "View",
      "path":   "/main/:type/{id:\\d+}",
      "target": "/pages/view.asp",
      "method": "*"
    },
    {
      "name":   "EditPage",
      "path":   "/main/:type/{id:\\d+}/edit",
      "target": "/pages/edit.asp",
      "method": "GET"
    },
    {
      "name":   "Edit",
      "path":   "/main/:type/{id:\\d+}/edit",
      "target": "/handlers/dev.edit",
      "method": "POST"
    },
    {
      "name":     "List",
      "path":     "/main/:type/list/{page:\\d*}",
      "target":   "/pages/list.asp",
      "method":   "*",
      "defaults": { "page": 1 }
    },
    {
      "name":   "Delete",
      "path":   "/main/:type/{id:\\d+}/delete",
      "target": "/handlers/dev.delete",
      "method": "POST"
    }
  ]
  ...
}
...

In your ASP scripts and Handlers:

<%
  # Get the router:
  my $router = $Config->web->router;
  
  # Get the uri:
  my $uri = $router->uri_for('EditPage', { type => 'truck', id => 123 });
%>
<a href="<%= $Server->HTMLEncode( $uri ) %>">Edit this Truck</a>

Comes out like this:

<a href="/main/truck/123/edit/">Edit this Truck</a>

DESCRIPTION

For a gentle introduction to URL Routing in general, see Router::Generic, since ASP4x::Router uses Router::Generic to handle all the routing logic.

Long story short - URL Routing can help decouple the information architecture from the actual layout of files on disk.

How does it work?

ASP4x::Router uses Router::Generic for the heavy lifting. It functions as both a mod_perl PerlTransHandler and as a ASP4::RequestFilter, providing the same exact routing behavior for both ASP4::API calls and for normal HTTP requests handled by the mod_perl interface of your web server.

When a request comes in to Apache, mod_perl will know that ASP4x::Router might make a change to the URI - so it has ASP4x::Router take a look at the request. If any changes are made (eg - /foo/bar/1/ gets changed to /pages/baz.asp?id=1) then the server handles the request just as though /pages/baz.asp?id=1 had been requested in the first place.

For testing - if you run this:

$api->ua->get('/foo/bar/1/');

ASP4x::Router will "reroute" that request to /pages/baz.asp?id=1 as though you had done it yourself like this:

$api->ua->get('/pages/baz.asp?id=1');

What is the point?

Aside from the "All the cool kids are doing it" argument - you get super SEO features and mad street cred - all in one shot.

Now, instead of 1998-esque urls like /page.asp?category=2&product=789&revPage=2 you get /shop/marbles/big-ones/reviews/page/4/

What about performance?

Unless you have literally *thousands* of different entries in the "routing" section of your conf/asp4-config.json file, performance should be quite fast.

Where can I learn more?

Please see the documentation for Router::Generic to learn all about how to specify routes.

PREREQUISITES

ASP4, Router::Generic

AUTHOR

John Drago <jdrago_999@yahoo.com>

LICENSE

This software is Free software and may be used and redistributed under the same terms as any version of Perl itself.