NAME

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

VERSION

version 0.04

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 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) 2012 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.