# NAME

Plack::Middleware::ComboLoader - Handle combination loading and processing of on-disk resources.

# VERSION

version 0.01

# SYNOPSIS

    use Plack::Builder;

    # Whatever your Plack app may be, though using this with
    # Plack::App::File works very well!
    my $app = [ 200, [ 'Content-Type' => 'plain/text' ], 'Hello' ];
    builder {
        enable "ComboLoader",
            # Defaults to this, goes out 10 years. 
            max_age => 315360000,
            roots => {
                'yui3'         => 'yui3/',
                'yui3-gallery' => 'yui3-gallery/',
                'our-gallery'  => 'our-gallery/',
                # Or, if you want to run each file through something:
                '/static/css' => {
                    path      => 'static/css',
                    processor => sub {
                        # $_ isa Path::Class::File object
                        # It is much, much better to minify as a build process
                        # and not on demand.
                        CSS::Minifier::minify( input => $_->slurp );
                        # This method returns a *string*
                    }
                }
            },
            # Optional parameter to save generated files to this path:
            # If the file is there and it's not too old, it gets served.
            # If it is too old (the expires below), it will be regenerated.
            save => 'static/combined',
            expires => 86400, # Keep files around for a day.
        $app;
    };

# DESCRIPTION

This is (another) combination loader for static resources. This is designed to
operate with the YUI3 Loader Service.

You can specify multiple points, and if all files are of the same type it sets
the mime-type and all proper caching headers for the browser.

The incoming requests will look like:

    http://my.cdn.com/rootName?3.4.1/build/module/module.js&3.4.1/build/module2/module2.js

The rootName specifies the path on disk, and each query arg is a file under the
path.

# PROCESSING FILES

I highly recommend doing minifying and building prior to any serving. This way
files stay on disk, unmodified and perform better.  If, however, you want to
do any processing (like compiling templates into JavaScript, a la Handlebars)
you can do that.

Use the `processor` option, you can munge your files however you wish.

The sub is passed in a [Path::Class::File](http://search.cpan.org/perldoc?Path::Class::File) object, and should return a byte
encoded string. Plack will require it to be byte encoded, and you will have
incorrect results if you do not encode accordingly.

Whatever return value is appended to the output buffer and sent to the client.

# CONFIGURATION

There are the following configuration settings:

- roots

The only required parameter for anything to actually happen. This is a list
of roots and the directories in which to look at files.

    roots => {
        'yui3' => '/var/www/builds/yui3',
        'yui2' => '/var/www/builds/yui2',
    }

That configuration would create combo roots for yui3 and yui2, handling links
as expected.

- max_age

Specify an alternate max-age header and Expires, this defaults to 10 years out.

- save

Should we save the resulting file to disk? Probably not, but sometimes a bad
idea can be good. It's better to instead use a caching middleware or frontend.

If the item exists on disk, and is not too old (see expires option below), this
will serve the file directly.

The intention is not for performance really, but for pregenerating files that
may take a long time or external information (and a reasonable fallback).

- expires

Specify how long a file on disk is valid before regenerating. If you are
pregenerating files, make sure this is set far enough in the future they never
grow stale.

# AUTHOR

J. Shirley <j@shirley.im>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Infinity Interactive, Inc.

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