NAME

Catalyst::Plugin::ExternalURI - Rewrite URLs generated with uri_for

VERSION

Version 0.02

SYNOPSIS

Include ExternalURI in your Catalyst Plugin list to activate it

In MyApp.pm

    use Catalyst qw/ ... ExternalURI ... /;

In MyApps configuration:

    __PACKAGE__->config(
        externaluri => [
            # Converts urls with the form of /static/css to start with another domain name 
            { '^/static' => 'http://static.mydomain.com' },
            ...
            { 'MATCH' => 'REWRITE' }
            or
            { match => '^/static', rewrite => 'http://static.mydomain.com' },
        ]
    );

DESCRIPTION

This plugin helps you rewrite the URLs generated by uri_for (and uri_for_action) so they can point to different domains (not necesarily hosted by your application).

USE CASES

Enable static content to be hosted in external services

If you upload your resources to services like Amazon S3, CloudFiles, or CDNs you can easily change the appropiate urls in your application to point to the resources on that provider.

  { '^/static/' => 'http://yours3bucket.s3.amazonaws.com/' }

  # $c->uri_for('/static/css/main.css') gets converted into
  # http://yours3bucket.s3.amazonaws.com/static/css/main.css

Enable parallel download of resources

Since your pages now point to various domains, your browser will open parallel connections to those domains (enabling faster pages loads). Try splitting images, js and css to load from different domains.

  { '^/static/css/' => 'http://css.myapp.com/' },
  { '^/static/js/'  => 'http://js.myapp.com/' },

  # $c->uri_for('/static/css/main.css') gets converted into
  # http://css.myapp.com/static/css/main.css
  # $c->uri_for('/static/js/framework.js') gets converted into
  # http://js.myapp.com/static/js/framework.js

Avoid cache problems

You can prefix a version number to all your static URLs. That way, when you deploy, you can point all your static contents to fresh, new, uncached versions of your files.

  { '^/static' => 'http://js.mydomain.com/v1' }

  # $c->uri_for('/static/js/framework.js') gets converted into
  # http://js.myapp.com/v1/static/js/framework.js

Configuration

The externaluri key of the configuration has to contain an ARRAY of RULES. Each call to uri_for will evaluate the RULES in the configuration of the plugin.

Each rule is a hashref that has the form of:

  { 'REGEX' => 'REWRITE' }

or

  { match => 'REGEX', rewrite => 'REWRITE' [, continue => 1 ] }

Each rules match is evaluated against the uri that is passed to uri_for. When a key matches the uri, the REWRITE gets applied, and evaluation of rules is interrupted, unless stated in the rule with a continue key with a value of 1.

REWRITE rules force specific portions of a url to their specification:

https:// Forces the scheme part of the URL to be https. All other elements are unchanged

http://mydomain.com Will force the scheme to http, and the host part of the URL to mydomain.com

/v3 Will force a prefix in the path of the URL

http://mybucket.s3.amazonaws.com/v1 Will force scheme to http, change the host, and prefix the URI part with /v1

CAVEAT

Be specific with your matches

'/static' will match uris like '/im/not/static'. This is supported, but it may not be what you meant to do. You probably meant '^/static'

AUTHOR

Jose Luis Martinez (JLMARTIN)

Miquel Ruiz (MRUIZ)

COPYRIGHT

cpanm Catalyst::Plugin::ExternalURI

perl -MCPAN -e shell
install Catalyst::Plugin::ExternalURI