NAME
CGI::Application::URIMapping - A dispatcher and permalink builder
SYNOPSIS
package MyApp::URIMapping;
use base qw/CGI::Application::URIMapping/;
use MyApp::Page1;
use MyApp::Page2;
package MyApp::Page1;
use base qw/CGI::Application/;
# registers subroutine ``page1'' for given path
MyApp::URIMapping->register({
path => 'page1/:p1/:p2?',
query => [ qw/q1 q2 q3/ ]
});
sub page1 {
...
}
# build_uri, generates: http://host/page1/p-one?q1=q-one&q3=q-three
my $permalink = MyApp::Page1->build_uri([{
p1 => 'p-one',
q1 => 'q-one',
q3 => 'q-three',
}]);DESCRIPTION
CGI::Application::URIMapping is a dispatcher / permalink builder for CGI::Application. It is implemented as a wrapper of CGI::Application::Dispatch.
As can be seen in the synopsis, CGI::Application::URIMapping is designed to be used as a base class for defining a mapping for each CGI::Application-based web application.
METHODS
register
The class method assigns a runmode to more than one paths. There are various ways of calling the function. Runmodes of the registered packages are automatically setup, and Build_uri method will be added to the packages.
MyApp::URIMapping->register('path');
MyApp::URIMapping->register('path/:required_param/:optional1?/:optional2?');
MyApp::URIMapping->register({
path => 'path',
query => [ qw/n1 n2/ ],
});
MyApp::URIMapping->register({
rm => 'run_mode',
path => 'path',
protocol => 'https',
host => 'myapp.example.com',
});
MyApp::URIMapping->register({
app => 'MyApp::Page2',
rm => 'run_mode',
path => [
'path1/:p1/:p2?/:p3?' => {
query => [ qw/n1 n2/ ],
},
'path2' => {
query => [ qw/p1 p2 p3 n1 n2/ ],
},
],
});The attributes recognized by the function is as follows.
app
Name of the package in which the run mode is defined. If ommited, name of the current package is being used.
rm
Name of the runmode. If omitted, basename of the first path attribute is being used.
path
A path (or an array of paths) to be registered for the runmode. The syntax of the paths are equivalent to that of CGI::Application::Dispatch with the following exceptions. The attributes app and rm need not be defined for each path, since they are already specified. Procotol, host, query attributes are accepted.
protocol
Specifies protocol to be used for given runmode when building a permalink.
host
Limits the registration to given host if specified.
query
List of parameters to be marshallised when building a premalink. The parameters will be marshallized in the order of the array.
build_uri
The function is automatically setup for the registered CGI::Application packages.
MyApp::Page1->build_uri(); # builds default URI for page1
MyApp::Page1->build_uri({ # explicitly set runmode
rm => 'page1',
});
MyApp::Page1->build_uri({ # specify parameters and protocol
params => [{
p1 => 'p-one',
n1 => 'n-one',
}],
procotol => 'https',
});
MyApp::Page1->build_uri({ # just override 'p1'
params => [
{
p1 => 'p-one',
},
$cgi_app,
$cgi_app->query,
],
});If called with a hash as the only argument, the function recognizes the following attributes. If called with an array as the only argument, the array is considered as the params attribute.
rm
Name of the runmode. If omitted, the last portion of the package name will be used uncamelized.
protocol
Protocol.
params
An array of hashes or object containing values to be filled in when building the URI. The parameters are searched from the begging of the array to the end, and the first-found value is used. If the array element is an object, its param method is called in order to obtain the variable.
AUTHOR
Copyright (c) 2007 Cybozu Labs, Inc. All rights reserved.
written by Kazuho Oku <kazuhooku@gmail.com>
LICENSE
This program is free software; you can redistribute it and/or modify it under th e same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html