Cascading style sheets and their media types

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

    [% 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)

    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

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

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->new( base => <base>, output_path => <output_path>, minify => <minify> )

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>, { ... } ])

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({ ... })

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>, { ... } ])

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

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

Returns the name of $assets

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

$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> ])

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

$assets->empty

$assets->exists( <path> )

$assets->store( <asset> )

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

Returns undef if nothing at <path> exists yet

$assets->set_name( <name> )

This is exactly the same as

    $assets->name( <name> )

$assets->set_base( <base> )

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

$assets->set_base_dir( <dir> )

$assets->set_base_path( <path> )

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

$assets->set_output_path( <path> )

See "Specifying an "output_path" pattern" above

$assets->set_cache( <cache> )