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

VERSION
    Version 0.001

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
