NAME

PEF::Front::Route - Routing of incoming requests

DESCRIPTION

PEF::Front has already pre-defined routing schema. This document describes this schema and methods to amend it.

ROUTING

Incoming requests must be associated with their handlers. Standard schema is following:

/app$Template

Returns processed template. Its file name is a lower-case converted from CamelCase form. Like: /appIndex -> index.html, /appUserSettings -> user_settings.html. It's possible to have some extra parameters like /appArticle/id-283 and then parameter id will be equal to "283". Without parameter name this value will be put into parameter cookie.

See cfg_parse_extra_params in PEF::Front::Config.

/ajax$Method

Returns JSON answer, doesn't support redirects. By default doesn't parse parameters from URI path. Method name is lower-case converted from CamelCase form: /ajaxGetUserInfo -> "get user info".

/submit$Method

It's like /ajax$Method but support redirects and content can be in any form.

/get$Method

It's like /submit$Method but by default parses parameters from URI path.

CUSTOM PRFIXES

add_prefix_handler($prefix, $handler)

Application can define its own prefix handlers /$prefix$Method. $handler is a code reference that receives ($request, $context).

RULES

Using routing rules this schema can be changed completely. You can import your routing rules in PEF::Front::Route or add them with PEF::Front::Route::add_route(@rules).

  use PEF::Front::Route ('/' => '/appIndex');
  

or

  use PEF::Front::Route;
  PEF::Front::Route::add_route('/' => '/appIndex');
  

Routing is always given by pairs: rule => destination. Destination can be simple value or 2 or 3-elements array with value, flags and PEF::Front::Response object.

flags can be string like "L=404" or hash like {L => 404}. In string form flags are separated by space or comma.

  PEF::Front::Route::add_route(
    '/'        => '/appIndex',
    '/me'      => ['/appUser', 'L'],
    '/oldpath' => ['/', 'R=301'],
  );

Following flags are recognized:

R

By default it's temporary redirect but status parameter can change it, for example R=301 means permanent redirect. This flag automatically means 'Last destination'.

L

Last destination. Parameter can set response status: L=404.

RE

Regexp flags for matching or substitution operator. Like RE=g.

Following combinations of rules and destinations are supported:

string => string

Replaces one path with another.

Regexp => string

Transformation function is simple regexp substitution: s"$regexp"$string"$flags.

  qr"/index(.*)" => '/appIndex$1'

Regexp => CODE.

If m"$regexp"$flags is true then supplied function is called with params ($request, @params), where @params is array of matched groups of $regexp.

string => CODE

When path is exactly equal to the strng then supplied subroutine is called with parameter ($request).

CODE => string

When supplied subroutine with parameter ($request) returns true then path is replaces with the string.

CODE = CODE

When supplied subroutine with parameter ($request) returns true then second subroutine called with params ($request, @params) where @params is result of first matching function.

CODE => undef

Supplied function with parameter ($request) checks path and returns new destination.

Routing process is executed in order of rules addition. Final destination of the routing process can have one of supported prefixes or point to some static content. If static content is not supported or no such content found then response with 404 status is returned.

Using CODE => undef you can implement any URL mapping that you wish.

  # quasi-RESTful

  sub my_routing {
    my $path = $_[0]->path;
    my ($resource, $id) = $path =~ m{^/([^/]+)/?([^/]+)?};
    $resource = ucfirst $resource;
    my $action = ucfirst lc $_[0]->method;
    $_[0]->param(id => $id) if defined $id;
    return ["/ajax$action$resource", "L"];
  }
  
  PEF::Front::Route::add_route(\&my_routing => undef);

During routing process you can change request parameters and put some notes to it. See note($key [, $value]) in PEF::Front::Request.

This module exports these functions: get post patch put delete websocket sse to help with HTTP method filtering.

  PEF::Front::Route::add_route(
    get  '/' => '/appIndex',
    post '/' => '/ajaxLogin',
  );

APPLICATION ENTRY POINT

You startup file must return reference to subroutine that accept incoming request. PEF::Front::Route-to_app()> is this reference. Your last line in startup file usually should be

  PEF::Front::Route->to_app(); 
  

AUTHOR

This module was written and is maintained by Anton Petrusevich.

Copyright and License

Copyright (c) 2016 Anton Petrusevich. Some Rights Reserved.

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

cpanm PEF::Front

perl -MCPAN -e shell
install PEF::Front