[Catalyst-dev] RFC: Catalyst::Plugin::SmartURI

[Rafael Kitover]

I've uploaded a dev release to CPAN as:
Catalyst-Plugin-SmartURI-0.01_01.tar.gz
http://pause.perl.org/incoming/Catalyst-Plugin-SmartURI-0.01_01.tar.gz
It's in svn here:
http://dev.catalystframework.org/svnweb/Catalyst/browse/Catalyst-Plugin-SmartURI/1.000/trunk/

mst came up with the design on #catalyst, implementation is close to 
what he suggested.

docs are probably not that great yet...

NAME
       Catalyst::Plugin::SmartURI - Configurable URIs for Catalyst

VERSION
       Version 0.01_01

SYNOPSIS
           smarturi:
               disposition: hostless # application-wide

           $c->uri_disposition('absolute'); # per request

           <a href="[% c.uri_for('/foo').relative %]" ...

       Configure whether $c->uri_for and $c->req->uri_with return absolute,
       hostless or relative URIs and/or configure which URI class to use, on
       an application or request basis.

       This is useful in situations where you’re for example, 
redirecting to a
       lighttpd from a firewall rule, instead of a real proxy, and you want
       your links and redirects to still work correctly.

DESCRIPTION
       This plugin allows you to configure, on a application and per-request
       basis, what URI class $c->uri_for and $c->req->uri_with use, as 
well as
       whether the URIs they produce are absolute, hostless or relative.

       To use your own URI class, just subclass Catalyst::SmartURI and set
       uri_class, or write a class that follows the same interface.

       This plugin installs a custom $c->request_class, however it does 
so in
       a way that won’t break if you’ve already set your own request_class.

       There will be a slight performance penalty for your first few 
requests,
       due to the way Catalyst::SmartURI works, but after that you shouldn’t
       notice it. The penalty is considerably smaller in perl 5.10+.

CONFIGURATION
       In myapp.yml:

           smarturi:
               dispostion: absolute
               uri_class: 'Catalyst::SmartURI'

       disposition
           One of ’absolute’, ’hostless’ or ’relative’. Defaults to
           ’absolute’.

       uri_class
           The class to use for URIs, defaults to Catalyst::SmartURI.

PER REQUEST
           package MyAPP::Controller::RSSFeed;

           ...

           sub begin : Private {
               my ($self, $c) = @_;

               $c->uri_class('Your::URI::Class'); # if you need
               $c->uri_disposition('absolute'); # rest of app configured 
differently
           }

       $c->uri_disposition(’absolute’|’hostless’|’relative’)
           Set URI disposition to use for the duration of the request.

       $c->uri_class($class)
           Set the URI class to use for $c->uri_for and 
$c->req->uri_with for
           the duration of the request.

EXTENDING
       $c->prepare_uri actually creates the URI, you can overload that to do
       as you please in your own plugins.