NAME
    File::Assets - Manage .css and .js assets for a web page or application

VERSION
    Version 0.064_1

SYNOPSIS
        use File::Assets

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

        # Put minified files in $dir_root/built/... (the trailing slash is important)
        $assets->set_output_path("built/")

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

        # You can also include external assets:
        $assets->include("http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.min.js");

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

        # And finally ...
        $assets->export

        # Or you can iterate (in order)
        for my $asset ($assets->exports) {
        
            print $asset->uri, "\n";

        }

    In your .tt (Template Toolkit) files:

        [% WRAPPER page.tt %]

        [% assets.include("/static/special-style.css", 100) %] # The "100" is the rank, which makes sure it is exported after other assets

        [% asset = BLOCK %]
        <style media="print">
        body { font: serif; }
        </style>
        [% END %]
        [% assets.include(asset) %] # This will include the css into an inline asset with the media type of "print"

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

    Use the minify option to perform minification before export

        my $assets = File::Assets->new( minify => 1, ... )

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,
    CSS::Minifier, JavaScript::Minifier::XS, and CSS::Minifier::XS.

    File::Assets was built with Catalyst in mind, although this package is
    framework agnostic. Look at Catalyst::Plugin::Assets for an easy way to
    integrate File::Assets with Catalyst.

USAGE
  Cascading style sheets and their media types
    A cascading style sheet can be one of many different media types. For
    more information, look here: <http://www.w3.org/TR/REC-CSS2/media.html>

    This can cause a problem when minifying, since, for example, you can't
    bundle a media type of screen with a media type of print. File::Assets
    handles this situation by treating .css files of different media types
    separately.

    To control the media type of a text/css asset, you can do the following:

        $assets->include("/path/to/printstyle.css", ..., { media => "print" }); # The asset will be exported with the print-media indicator

        $assets->include_content($content, "text/css", ..., { media => "screen" }); # Ditto, but for the screen type

  Including assets in the middle of processing a Template Toolkit template
    Sometimes, in the middle of a TT template, you want to include a new
    asset. Usually you would do something like this:

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

    But then this will show up in your output, because ->include returns an
    object:

        File::Assets::Asset=HASH(0x99047e4)

    The way around this is to use the TT "CALL" directive, as in the
    following:

        [% CALL assets.include("/include/style.css") %]

  Avoid minifying assets on every request (if you minify)
    By default, File::Assets will avoid re-minifying assets if nothing in
    the files have changed. However, in a web application, this can be a
    problem if you serve up two web pages that have different assets. That's
    because File::Assets will detect different assets being served in page A
    versus assets being served in page B (think AJAX interface vs. plain
    HTML with some CSS). The way around this problem is to name your assets
    object with a unique name per assets bundle. By default, the name is
    "assets", but can be changed with $assets->name(<a new name>):

        my $assets = File::Assets->new(...);
        $assets->name("standard");

    You can change the name of the assets at anytime before exporting.

  YUI Compressor 2.2.5 is required
    If you want to use the YUI Compressor, you should have version 2.2.5 or
    above.

    YUI Compressor 2.1.1 (and below) will *NOT WORK*

    To use the compressor for minification specify the path to the .jar like
    so:

        my $assets = File::Assets->new( minify => "/path/to/yuicompressor.jar", ... )

  Specifying an "output_path" pattern
    When aggregating or minifying assets, you need to put the result in a
    new file.

    You can use the following directives when crafting a path/filename
    pattern:

        %n      The name of the asset, "assets" by default
        %e      The extension of the asset (e.g. css, js)
        %f      The fingerprint of the asset collection (a hexadecimal digest of the concatenated digest of each asset in the collection)
        %k      The kind of the asset (e.g. css-screen, css, css-print, js)
        %h      The kind head-part of the asset (e.g. css, js)
        %l      The kind tail-part of the asset (e.g. screen, print) (essentially the media type of a .css asset)

    In addition, in each of the above, a ".", "/" or "-" can be placed in
    between the "%" and directive character. This will result in a ".", "/",
    or "-" being prepended to the directive value.

    The default pattern is:

        %n%-l%-f.%e

    A pattern of "%n%-l.%e" can result in the following:

        assets.css          # name of "assets", no media type, an asset type of CSS (.css)
        assets-screen.css   # name of "assets", media type of "screen", an asset type of CSS (.css)
        assets.js           # name of "assets", an asset type of JavaScript (.js)

    If the pattern ends with a "/", then the default pattern will be
    appended

        xyzzy/          => xyzzy/%n%-l-%f.%e

    If the pattern does not have an extension-like ending, then "%.e" will
    be appended

        xyzzy           => xyzzy.%e

  Strange output or "sticky" content
    File::Assets uses built-in caching to share content across different
    objects (via File::Assets::Cache). If you're having problems try
    disabling the cache by passing "cache => 0" to File::Assets->new

METHODS
  File::Assets->new( base => <base>, output_path => <output_path>, minify => <minify> )
    Create and return a new File::Assets object.

    You can configure the object with the following:

        base            # A hash reference with a "uri" key/value and a "dir" key/value.
                          For example: { uri => http://example.com/assets, dir => /var/www/htdocs/assets }
    
                        # A URI::ToDisk object

                        # A Path::Resource object

        minify          # "1" or "best" - Will either use JavaScript::Minifier::XS> & CSS::Minifier::XS or
                                          JavaScript::Minifier> & CSS::Minifier (depending on availability)
                                          for minification

                        # "0" or "" or undef - Don't do any minfication (this is the default)

                        # "./path/to/yuicompressor.jar" - Will use YUI Compressor via the given .jar for minification

                        # "minifier" - Will use JavaScript::Minifier & CSS::Minifier for minification

                        # "xs" or "minifier-xs" - Will use JavaScript::Minifier::XS & CSS::Minifier::XS for minification

        output_path     # Designates the output path for minified .css and .js assets
                          The default output path pattern is "%n%-l%-d.%e" (rooted at the dir of <base>)
                          See above in "Specifying an output_path pattern" for details

  $asset = $assets->include(<path>, [ <rank>, <type>, { ... } ])
  $asset = $assets->include_path(<path>, [ <rank>, <type>, { ... } ])
    First, if <path> is a scalar reference or "looks like" some HTML (starts
    with a angle bracket, e.g.: <script></script>), then it will be treated
    as inline content.

    Otherwise, this will 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.

    By default, the newly created $asset is NOT inline.

    Returns the newly created asset.

    NOTE: See below for how the extra hash on the end is handled

  $asset = $assets->include({ ... })
    Another way to invoke include is by passing in a hash reference.

    The hash reference should contain the follwing information:

        path        # The path to the asset file, relative to base
        content     # The content of the asset

        type        # Optional if a path is given, required for content
        rank        # Optional, 0 by default (Less than zero is earlier, greater than zero is later)
        inline      # Optional, by default true if content was given, false is a path was given
        base        # Optional, by default the base of $assets

    You can also pass extra information through the hash. Any extra
    information will be bundled in the ->attributes hash of $asset. For
    example, you can control the media type of a text/css asset by doing
    something like:

        $assets->include("/path/to/printstyle.css", ..., { media => "print" }) # The asset will be exported with the print-media indicator

    NOTE: The order of <rank> and <type> doesn't really matter, since we can
    detect whether something looks like a rank (number) or not, and correct
    for it (and it does).

  $asset = $assets->include_content(<content>, [ <type>, <rank>, { ... } ])
    Include an asset with some content and of the supplied type. The value
    of <content> can be a "plain" string or a scalar reference.

    You can include content that looks like HTML:

        <style media="print">
        body {
            font: serif;
        }
        </style>

    In the above case, <type> is optional, as File::Assets can detect from
    the tag that you're supplying a style sheet. Furthermore, the method
    will find all the attributes in the tag and put them into the asset. So
    the resulting asset from including the above will have a type of
    "text/css" and media of "print".

    For now, only <style> and <script> will map to types (.css and .js,
    respectively)

    See ->include for more information on <rank>.

    By default, the newly created $asset is inline.

    Returns the newly created asset.

    NOTE: The order of the <type> and <rank> arguments are reversed from
    ->include and ->include_path Still, the order of <rank> and <type>
    doesn't really matter, since we can detect whether something looks like
    a rank (number) or not, and correct for it (and it does).

  $name = $assets->name([ <name> ])
    Retrieve and/or change the "name" of $assets; by default it is "assets"

    This is useful for controlling the name of minified assets files.

    Returns the name of $assets

  $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

  $assets->set_name( <name> )
    Set the name of $assets

    This is exactly the same as

        $assets->name( <name> )

  $assets->set_base( <base> )
    Set the base uri, dir, and path for assets

    <base> can be a Path::Resource, URI::ToDisk, or a hash reference of the
    form:

        { uri => ..., dir => ..., path => ... }

    Given a dir of "/var/www/htdocs", a uri of "http://example.com/static",
    and a path of "assets" then:

        $assets will look for files in "/var/www/htdocs/assets"

        $assets will "serve" files with "http://example.com/static/assets"

  $assets->set_base_uri( <uri> )
    Set the base uri for assets

  $assets->set_base_dir( <dir> )
    Set the base dir for assets

  $assets->set_base_path( <path> )
    Set the base path for assets

    Passing an undefined value for <path> will clear/get-rid-of the path

  $assets->set_output_path( <path> )
    Set the output path for assets generated by $assets

    See "Specifying an "output_path" pattern" above

  $assets->set_cache( <cache> )
    Specify the cache object or cache name to use

AUTHOR
    Robert Krimen, "<rkrimen at cpan.org>"

SEE ALSO
    Catalyst::Plugin::Assets

    Google::AJAX::Library

    JS::YUI::Loader

    JS::jQuery::Loader

SOURCE
    You can contribute or fork this project via GitHub:

    <http://github.com/robertkrimen/file-assets/tree/master>

        git clone git://github.com/robertkrimen/file-assets.git File-Assets

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:

    * RT: CPAN's request tracker
        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-Assets>

    * AnnoCPAN: Annotated CPAN documentation
        <http://annocpan.org/dist/File-Assets>

    * CPAN Ratings
        <http://cpanratings.perl.org/d/File-Assets>

    * Search CPAN
        <http://search.cpan.org/dist/File-Assets>

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.

