/ 
Catalyst-Plugin-Assets-0.012
River stage one • 1 direct dependent • 1 total dependent
/ Catalyst::Plugin::Assets

NAME

Catalyst::Plugin::Assets - Manage and minify .css and .js assets in a Catalyst application

VERSION

Version 0.012

SYNOPSIS

# In your Catalyst application... 

use Catalyst qw/-Debug Assets Static::Simple/;
# Static::Simple is not *required*, but C::P::Assets does not serve files by itself!

# This is all you need. Now your $catalyst object will now have an ->assets method.

# Sometime during the request ...

sub some_action : Local {
    my ($self, $catalyst) = @_;
    
    ...

    $catalyst->assets->include("stylesheet.css");

    ...
}

# Then, in your .tt (or whatever you're using for view processing):

<html>
<head><title>[% title %]</title>

[% catalyst.assets.export %]

</head>
<body>

...

DESCRIPTION

Catalyst::Plugin::Assets integrates File::Assets into your Catalyst application. Essentially, it provides a unified way to include .css and .js assets from different parts of your program. When you're done processing a request, you can use $catalyst->assets->export() to generate HTML or $catalyst->assets->exports() to get a list of assets.

In addition, C::P::Assets includes support for minification via YUI compressor, JavaScript::Minifier, and CSS::Minifier (and a rudimentary concatenation filter)

Note that Catalyst::Plugin::Assets does not serve files directly, it will work with Static::Simple or whatever static-file-serving mechanism you're using.

A brief description of File::Assets

File::Assets is a tool for managing JavaScript and CSS assets in a (web) application. It allows you to "publish" assests in one place after having specified them in different parts of the application (e.g. throughout request and template processing phases).

File::Assets has the added bonus of assisting with minification and filtering of assets. Support is built-in for YUI Compressor (http://developer.yahoo.com/yui/compressor/), JavaScript::Minifier, and CSS::Minifier. Filtering is fairly straightforward to implement, so it's a good place to start if need a JavaScript or CSS preprocessor (e.g. something like HAML http://haml.hamptoncatlin.com/)

CONFIGURATION

You can configure C::P::Assets by manipulating the $catalyst->config->{assets} hash.

The following settings are available:

path        # A path to automatically look for assets under (e.g. "/static" or "/assets")

            # This path will be automatically prepended to includes, so that instead of
            # doing ->include("/static/stylesheet.css") you can just do ->include("stylesheet.css")
            

output      # The path to output the results of minification under (if any).

            # For example, if output is "built/" (the trailing slash is important), then minified assets will be
            # written to "root/<assets-path>/built/..."


minify      # '1' to use JavaScript::Minifier and CSS::Minifier for minification
            # 'yui-compressor:<path-to-yui-compressor-jar>' to use YUI Compressor


stash_var   # The name of the key in the stash that provides the assets object (accessible via $catalyst->stash->{<stash_var}.
            # By default, the <stash_var> is "assets".
            # To disable the setting of the stash variable, set <stash_var> to undef

Example configuration

Here is an example configuration:

# Under the configuration below, the assets object will automatically
# look for assets (.css and .js files) under <home>/root/static/*
# If it needs to generate a minified asset, it will deposit the generated asset under <home>/root/static/built/*

# To turn off minification, set minify to 0

# Finally, the assets object is also available via $catalyst->stash->{assets} (This is actually the default setting)

__PACKAGE__->config(
    
    name => 'Example',

    assets => {

        path => "/static",
        output => "built/",
        minify => 1,

        stash_var => "assets", # This is the default setting
    },

);

# Later, to include "http://localhost/static/example.css", do:

$catalyst->assets->include("example.css");

# To include "http://localhost/static/example.js", do:

$catalyst->assets->include("example.js");

METHODS

assets

Return the File::Assets object that exists throughout the lifetime of the request

AUTHOR

Robert Krimen, <rkrimen at cpan.org>

BUGS

Please report any bugs or feature requests to bug-catalyst-plugin-assets at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-Plugin-Assets. 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::Assets

You can also look for information at:

SEE ALSO

File::Assets, JavaScript::Minifier, CSS::Minifier, http://developer.yahoo.com/yui/compressor/, Catalyst

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Robert Krimen, all rights reserved.

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