Rafael Kitover > Catalyst-Plugin-SmartURI > Catalyst::Plugin::SmartURI

Download:
Catalyst-Plugin-SmartURI-0.039.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.039   Source  

NAME ^

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

SYNOPSIS ^

In your lib/MyApp.pm, load the plugin and your other plugins, for example:

    use Catalyst qw/
        -Debug
        ConfigLoader
        Static::Simple
        Session
        Session::Store::Memcached
        Session::State::Cookie
        Authentication
        Authorization::Roles
        +CatalystX::SimpleLogin
        SmartURI
    /;

In your .conf:

    <Plugin::SmartURI>
        disposition host-header   # application-wide
        uri_class   URI::SmartURI # by default
    </Plugin::SmartURI>

Per request:

    $c->uri_disposition('absolute');

Methods on URIs:

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

DESCRIPTION ^

Configure whether $c->uri_for and $c->req->uri_with return absolute, hostless or relative URIs, or URIs based on the 'Host' header. Also allows configuring which URI class to use. Works on application-wide or per-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.

To use your own URI class, just subclass URI::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 $c->request_class yourself, ie. by using Catalyst::Action::REST (thanks mst!).

There is a minor performance penalty in perls older than 5.10, due to Class::C3, but only at initialization time.

METHODS ^

$c->uri_for

$c->req->uri_with

Returns a $c->uri_class object (URI::SmartURI by default) in the configured $c->uri_disposition.

$c->req->uri

Returns a $c->uri_class object. If the context hasn't been prepared yet, uses the configured value for uri_class.

$c->req->uri->relative will be relative to $c->req->base.

$c->req->referer

Returns a $c->uri_class object for the referer (or configured uri_class if there's no context) with reference set to $c->req->uri if it comes from $c->req->base.

In other words, if referer is your app, you can do $c->req->referer->relative and it will do the right thing.

CONFIGURATION ^

In myapp.conf:

    <Plugin::SmartURI>
        disposition absolute
        uri_class   URI::SmartURI
    </Plugin::SmartURI>
disposition

One of 'absolute', 'hostless', 'relative' or 'host-header'. Defaults to 'absolute'.

The special disposition 'host-header' uses the value of your 'Host:' header.

uri_class

The class to use for URIs, defaults to URI::SmartURI.

PER REQUEST ^

    package MyAPP::Controller::RSSFeed;

    ...

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

        $c->uri_class('Your::URI::Class::For::Request');
        $c->uri_disposition('absolute');
    }
$c->uri_disposition('absolute'|'hostless'|'relative'|'host-header')

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, which you can override.

SEE ALSO ^

URI::SmartURI, Catalyst, URI

AUTHOR ^

Rafael Kitover, <rkitover at cpan.org>

BUGS ^

Please report any bugs or feature requests to bug-catalyst-plugin-smarturi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-Plugin-SmartURI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Catalyst::Plugin::SmartURI

You can also look for information at:

ACKNOWLEDGEMENTS ^

from #catalyst:

vipul came up with the idea

mst came up with the design and implementation details for the current version

kd reviewed my code and offered suggestions

TODO ^

I'd like to extend on Catalyst::Plugin::RequireSSL, and make a plugin that rewrites URIs for actions with an SSL attribute.

COPYRIGHT & LICENSE ^

Copyright (c) 2008 Rafael Kitover

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

syntax highlighting: