', view2path(\&add_new_article);
# -- or redirecting to another url
my $h = CGI::Easy::Headers->new();
$h->redirect(view2path(\&show_home_page));
These two parts (setup_path() with path2view() and setup_view() with
view2path()) can be used independently - for example, you don't have to
use setup_view() and view2path() if you prefer to hardcode urls in HTML
templates instead of generating them dynamically. But using both parts
will let you configure all urls used in your application in single
place, which make it easier to control and modify them.
In addition to simple constant path to handler and vice versa mapping
you can also map any path matching regular expression and even copy
some data from path to GET parameters. Example:
# make /article/123/ same as /index.php?id=123
# use same handler for any url beginning with /old/
setup_path(
'/article.php' => \&show_article,
qr{^/article/(\d+)/$} => set_param('id') => \&show_article,
qr{^/old/} => \&unsupported,
);
# generate urls like /article/123/ dynamically
setup_view(
\&show_article => [
with_params('id') => '/article/?/',
],
);
$url = view2path(\&show_article, id=>123);
INTERFACE
setup_path( [METHOD =>] MATCH => [CALLBACK => ...] HANDLER, ... )
Configure mapping of url's path to handler subroutine (which will be
used by path2view()). Can be called multiple times and will just add
new mapping rules on each call.
If optional METHOD parameter defined, then all mapping rules in this
setup_path() call will be applied only for requests with that HTTP
method. If METHOD doesn't used, then these rules will be applied to
all HTTP methods. If some path match both rules defined for current
HTTP method and rules defined for any HTTP methods, will be used rule
defined for current HTTP method.
MATCH parameter should be either SCALAR (string equal to url path) or
Regexp (which can match any part of url path).
HANDLER is REF to your subroutine, which will be returned by
path2view() when this rule will match current url.
Between MATCH and HANDLER any amount of optional CALLBACK subroutines
can be used. These CALLBACKs will be called when MATCH rule matches
current url with two parameters: CGI::Easy::Request object and
ARRAYREF with contents of all capturing parentheses (when MATCH rule
is Regexp with capturing parentheses). Usual task for such CALLBACKs
is convert "hidden" CGI parameters included in url path into usual
$r->{GET} parameters.
Return nothing.
path2view( $r )
Take CGI::Easy::Request object as parameter, and analyse this request
according to rules defined previously using setup_path().
Return: HANDLER if find rule which match current request, else
undef().
set_param( @names )
Take names of {GET} parameters which should be set using parts of url
path selected by capturing parentheses in MATCH Regexp.
Return CALLBACK subroutine suitable for using in setup_path().
setup_view( HANDLER => PATH, ... )
Configure mapping of handler subroutine to url path (which will be
used by view2path()). Can be called multiple times and will just add
new mapping rules on each call.
HANDLER must be REF to user's subroutine used to handle requests on
PATH.
PATH can be either STRING or ARRAYREF.
If PATH is ARRAYREF, then this array should consist of CALLBACK =>
TEMPLATE pairs. CALLBACK is subroutine which will be executed by
view2path() with single parameter \%params, and should return either
FALSE if this CALLBACK unable to handle these %params, or ARRAYREF
with values to substitute into path TEMPLATE. TEMPLATE is path STRING
which may contain '?' symbols - these will be replaced by values
returned in ARRAYREF by CALLBACK which successfully handle %params.
Example: map \&handler to /first/ or /second/ with 50% probability
setup_view(
\&handler => [
sub { return rand < 0.5 ? [] : undef } => '/first/',
sub { return [] } => '/second/',
],
);
Example: map \&handler to random article with id 0-999
setup_view(
\&handler => [
sub { return [ int rand 1000 ] } => '/article/?/',
],
);
Return nothing.
view2path( HANDLER, %params )
Take user handler subroutine and it parameters, and convert it to url
according to rules defined previously using setup_view().
Example:
setup_view(
\&handler => 'index.php',
);
my $url = view2path(\&handler, a=>'some string', b=>[6,7]);
# $url will be: 'index.php?a=some%20string&b=6&b=7'
If simple mapping from STRING to HANDLER was defined using
setup_path(), and this is only mapping to HANDLER defined, then it's
not necessary to define reverse mapping using setup_view() - it will
be defined automatically.
Example:
setup_path(
'/articles/' => \&list_articles,
);
my $url = view2path(\&list_articles);
# $url will be: '/articles/'
Return: url. Throw exception if unable to make url.
with_params( @names )
Take names of parameters which must exists in %params given to
view2path().
Return CALLBACK subroutine suitable for using in setup_view().
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at
https://github.com/powerman/perl-CGI-Easy-URLconf/issues. You will be
notified automatically of any progress on your issue.
Source Code
This is open source software. The code repository is available for
public review and contribution under the terms of the license. Feel
free to fork the repository and submit pull requests.
https://github.com/powerman/perl-CGI-Easy-URLconf
git clone https://github.com/powerman/perl-CGI-Easy-URLconf.git
Resources
* MetaCPAN Search
https://metacpan.org/search?q=CGI-Easy-URLconf
* CPAN Ratings
http://cpanratings.perl.org/dist/CGI-Easy-URLconf
* AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/CGI-Easy-URLconf
* CPAN Testers Matrix
http://matrix.cpantesters.org/?dist=CGI-Easy-URLconf
* CPANTS: A CPAN Testing Service (Kwalitee)
http://cpants.cpanauthors.org/dist/CGI-Easy-URLconf
AUTHOR
Alex Efros
COPYRIGHT AND LICENSE
This software is Copyright (c) 2009-2010 by Alex Efros
.
This is free software, licensed under:
The MIT (X11) License