NAME

PlackX::Framework::Router - Parse routes and export DSL for PXF apps

SYNOPSIS

package My::App::Controller {
  use My::App::Router;

  request_base '/myapp';

  filter before => sub ($request, $resp) { ... }

  filter after  => sub ($request, $resp) { ... }

  route '/'     => sub ($request, $resp) { ... }
}

EXPORTS

This module exports the subroutines "filter", "global_filter", "route", and "base" to the calling package. These can then be used like DSL keywords to lay out your web app.

You can choose your own keyword names by overridding them in your subclass this way:

package MyApp::Router {
  use parent 'PlackX::Framework::Router';
  sub filter_request_keyword        { 'my_filter'; }
  sub global_filter_request_keyword { 'my_global_filter' }
  sub route_request_keyword         { 'my_route';  }
  sub uri_base_keyword              { 'my_base';   }
}

For more detail, see the "DSL style" section.

CLASS-METHOD STYLE

You may add filters routes using class method calls, but this is not the preferred way to use this module.

Mixing class method style and DSL style routing in the same app is not recommended.

add_route($SPEC, \&ACTION, %OPTIONS)

Adds a route matching $SPEC to execute \&ACTION. In the future, %OPTIONS can contain keys 'base', 'prefilters', and/or 'postfilters'.

$ACTION should be a coderef, string containing a package and subroutine, e.g. "MyApp::Controller::index", or a hashref containing one of the keys 'template', 'text', or 'html' with the value being a string containing a template filename, plain text content to render, or html to render, respectively.

add_global_filter($WHEN, \&ACTION);

add_global_filter($WHEN, $PATTERN, \&ACTION);

Add a filter which will be applied to any route defined anywhere in the application. If $PATTERN is defined, the filter will only be executed if the request uri matches it. $PATTERN may be a string, scalar reference to a string, or regex; $PATTERN is the same as in DSL style described below.

\&ACTION is a reference to a subroutine. The subroutine should return a false value to continue with the next filter or route; if it returns a response object, processing will stop and the response will be rendered.

DSL-STYLE

request_base $STRING;

Set the base URI path for all subsequent routes defined in the current package.

filter before|after => sub { ... };

Filter all subsequent routes. Your filter subroutine should return a false value to continue request processing. $response->next is available for semantic convenience. To render a response early, return the response object.

global_filter before|after => sub { ... };

global_filter before|after => $PATTERN => sub { ... };

Adds a filter that can match any route anywhere in your application, regardless of where it is defined. Optionally, you may supply a $pattern which may be:

- a string, in which case the filter will be executed if the request uri BEGINS WITH the string.

- a scalar reference to a string, in which case the filter will be executed only if it matches the request path exactly

- a reference to a regular expression, e.g. qr|^/restricted| which will be used to match the request uri path.

route $URI_SPEC => $ACTION;

route $METHOD => $PATH => $ACTION;

route $ARRAYREF => $ACTION;

route $HASHREF => $ACTION;

Execute action \&ACTION for the matching uri described by $URI_SPEC. The $URI_SPEC may contain patterns described by PXF's routing engine, Router::Boom.

The $ACTION is a coderef, subroutine name, or hashref, as described in the class method add_route, described above.

The $METHOD may contain more than one method, separated by a pipe, for example, the string "get|post".

You may specify a list of $URI_SPECs in an $ARRAYREF.

You may specify a hashref of key-value pairs, where the key is the HTTP request method, and the value is the desired URI path.

See the section below for examples of various combinations.

EXAMPLES

# Base example
base '/myapp';

# Filter example
# Fat arrow operator allows us to use "before" or "after" without quotes.
filter before => sub ($request, $response) {
  unless ($request->{cookies}{logged_in}) {
    $response->status(403);
    return $response;
  }
  $request->{logged_in} = 1;
  return;
};

# Simple route
# Because of the request_base, this will actually match /myapp/index
route '/index' => sub { ... };

# Route with method
route get => '/default' => sub { ... }
route post => '/form'   => sub { ... }

# Route with method, alternate formats
route { get => '/login' } => sub { ... }

route { post => '/login' } => sub {
  # do some processing to log in a user..
  ...

  # successful login
  $request->redirect('/user/home');

  # reroute the request
  $request->reroute('/try_again');
};

# Route with arrayref
route ['/list/user', '/user/list', '/users/list'] => sub { ... };

# Routes with hashref
route { post => '/path1', put => '/path1' } => sub { ... };

# Route with pattern matching
# See Router::Boom for pattern options
route { delete => '/user/:id' } => sub {
  my $request = shift;
  my $id = $request->route_param('id');
};

# Combination hashref arrayref
route { get => ['/path1', '/path2'] } => sub {
  ...
};

# Routes with alternate HTTP verbs
route 'get|post' => '/somewhere' => sub { ... };

# Action hashref instead of coderef
# Key can be one of "template", "text", or "html"
route '/' => {
  template => 'index.tmpl'
};

route '/hello-world.txt' => {
  text => 'Hello World'
};

route '/hello-world.html' => {
  html => '<html><body>Hello World</body></html>'
};

META

For author, copyright, and license, see PlackX::Framework.