/ 
File-Assets-0.030
River stage one • 2 direct dependents • 3 total dependents
/ File::Assets

NAME

File::Assets - Manage .css and .js assets in a web application

VERSION

Version 0.030

SYNOPSIS

use File::Assets

my $assets = File::Assets->new( base => [ $uri_root, $htdocs_root ] );

$assets->include("/static/style.css"); # File::Assets will automatically detect the type based on the extension

# Then, later ...

$assets->include("/static/main.js");
$assets->include("/static/style.css"); # This asset won't get included twice, as File::Assets will ignore repeats of a path

# And then, in your .tt (Template Toolkit) files:

[% WRAPPER page.tt %]

[% assets.include("/static/special-style.css") %]

# ... finally, in your "main" template:

[% CLEAR -%]
<html>

    <head>
        [% assets.export("css") %]
    </head>

    <body>

        [% content %]

        <!-- Generally, you want to include your JavaScript assets at the bottom of your html -->

        [% assets.export("js") %]

    </body>

</html>

# If you want to process each asset individually, you can use exports:

for my $asset ($assets->exports) {

    print $asset->uri, "\n";
}

DESCRIPTION

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

This package 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/)

File::Assets was built with Catalyst in mind, although this package is framework agnostic.

METHODS

File::Assets->new( base => <base> )

Create and return a new File::Assets object. <base> can be:

* An array (list reference) where <base>[0] is a URI object or uri-like string (e.g. "http://www.example.com") and <base>[1] is a Path::Class::Dir object or a dir-like string (e.g. "/var/htdocs")

* A URI::ToDisk object

* A Path::Resource object

$asset = $assets->include(<path>, [ <rank>, <type> ])

$asset = $assets->include_path(<path>, [ <rank>, <type> ])

Include an asset located at "<base.dir>/<path>" for processing. The asset will be exported as "<base.uri>/<path>".

Optionally, you can specify a rank, where a lower number (i.e. -2, -100) causes the asset to appear earlier in the exports list, and a higher number (i.e. 6, 39) causes the asset to appear later in the exports list. By default, all assets start out with a neutral rank of 0.

Also, optionally, you can specify a type override as the third argument.

Returns the newly created asset.

$html = $assets->export([ <type> ])

Generate and return HTML for the assets of <type>. If no type is specified, then assets of every type are exported.

$html will be something like this:

<link rel="stylesheet" type="text/css" href="http://example.com/assets.css">
<script src="http://example.com/assets.js" type="text/javascript"></script>

@assets = $assets->exports([ <type> ])

Returns a list of assets, in ranking order, that are exported. If no type is specified, then assets of every type are exported.

You can use this method to generate your own HTML, if necessary.

$assets->empty

Returns 1 if no assets have been included yet, 0 otherwise.

$assets->exists( <path> )

Returns true if <path> has been included, 0 otherwise.

$assets->store( <asset> )

Store <asset> in $assets

$asset = $assets->fetch( <path> )

Fetch the asset located at <path>

Returns undef if nothing at <path> exists yet.

$name = $assets->name([ <name> ])

The name of the assets, by default it iss "assets".

AUTHOR

Robert Krimen, <rkrimen at cpan.org>

BUGS

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

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 Robert Krimen

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