percent results from the CPAN

Catalyst-Controller-AutoAssets
view release on metacpan or search on metacpan
lib/Catalyst/Controller/AutoAssets.pm view on Meta::CPAN
  <head>
    <link rel="stylesheet" type="text/css" href="[% c.controller('Assets::MyCSS').asset_path %]" />
  </head>

Or, to have the appropriate tags generated for you:

  <head>
    [% c.controller('Assets::MyCSS').html_head_tags %]
  </head>

Or, in static HTML:

  <head>
    <link rel="stylesheet" type="text/css" href="/assets/mycss/current.css" />
  </head>

=head1 PLUGIN INTERFACE

A Catalyst Plugin interface is also available for easy setup of multiple asset controllers at once. See

=over

=item L<Catalyst::Plugin::AutoAssets>

=back

=head1 DESCRIPTION

Fast, convenient and extendable serving of assets (CSS, JavaScript, Images, etc) at URL path(s) containing sha1 
checksums. This is an alternative/supplement to L<Catalyst::Plugin::Static::Simple> or
external/webserver for serving of an application's "nearly static" content.

The benefit of serving files through CAS paths ("content-addressable storage" - same design used by Git) 
is that it automatically alleviates client caching issues while simultaneously taking advantage of 
maximum aggressive HTTP cache settings. Because URL paths contain the sha1 checksum of the data, 
browsers can safely cache the content forever because "changes" automatically become new URLs. 
If the content (CSS, JavaScript or other) is modified later on, the client browsers instantly 
see the new version.

This is particularly useful when deploying new versions of an application where client browsers
out in the network might have cached CSS, JavaScript and Images from previous versions. Instead of asking 
users to hit "F5", everyone gets the new content automagically, with no intervention required (and no
sporadically broken user experiences when you forget to plan for cached data).
All you have to do is change the content; the module handles the rest.

This module also provides some optional extra features that are useful in both development and
production environments for automatically managing, minifying and deploying CSS, JavaScript, Image and Icon assets.

=head1 PERFORMANCE

Besides the performance benefits of aggressive HTTP caching (which can be significant, depending of the
ratio of first-time visitors to returning visitors) this module has also been optimized to serve requests
 as fast as possible. On typical requests, all that happens besides returning the content from
disk is one extra file stat and comparison of mtime. So, even with it's real-time content-change tracking and
checksums, this module is essentially identical to L<Catalyst::Plugin::Static::Simple> from a performance 
perspective (and may even be slightly faster because it caches guessed Content-Types instead of calculating on every
request like Static::Simple).

=head2 When to use this module

This module is great for development, web applications, and any production site with a high percentage of
returning users. If you want to take maximum advantage of HTTP caching without any work or planning, this module
is for you. Or, if you just want an easy and flexible way to manage static content, performance benefits aside,
this module is also for you.

=head2 When not to

The only cases where this module is not recommended is on very high-volume sites where most of the visits are
unique (i.e. little benefit from HTTP caching), or where the scale is large enough that the marginal
increase in speed of serving static content directly from the web server (like Apache), instead of through Catalyst,
is worth manually - and correctly - doing all the things that this module does automatically. Unless you are carefully
planning your HTTP caching strategy (such configuring Apache's cache settings) and coordinating all this with
content changes/new releases, this module is likely to outperform your manual setup.

=head1 HANDLERS

Note: All config params and methods described below are actually delegated to the type handler specified in 'type' and some are
specific (as noted below). For convenience, the core handlers C<Directory>, C<CSS> and C<JS> are documented below but others
are available (and custom handlers can also be written). To see other available type handlers and for information on writing 
custom handlers see:

=over

=item L<Catalyst::Controller::AutoAssets::Handler>

=back

=head1 CONFIG PARAMS

=head2 type

B<Required> - The asset type: C<Directory>, C<CSS>, C<JS>, etc.

The asset type is a "Handler" class name, and the core built in types are covered below. Custom handlers
can also be written. See L<Catalyst::Controller::AutoAssets::Handler> for details.

The C<Directory> asset type works in a similar manner as Static::Simple to make some directory
structure accessible at a public URL. The root of the structure is made available at the URL path:

  <CONTROLLER_PATH>/<SHA1>/

L<MIME::Types> is used to set the C<Content-Type> HTTP header based on
the file extension (same as Static::Simple does).

Because the sha1 checksum changes automatically and is unknown in advance, the above Asset Path is made available
via the C<asset_path()> controller method for use in TT files and throughout the application.

The C<CSS> and C<JS> types serve one automatically generated text file that is concatenated and
optionally minified from the include files. The single, generated file is made available at the URL 
Path:

  <CONTROLLER_PATH>/<SHA1>.js    # for 'JS' type
  <CONTROLLER_PATH>/<SHA1>.css   # for 'CSS' type

The js/css types provide a bonus mode of operation to provide a simple and convenient way to 
manage groups of CSS and JavaScript files to be automatically deployed in the application. This
is also particularly useful during development. Production applications with their own management
and build process for CSS and JavaScript would simply use the C<Directory> type.

=head2 no_logs
( run in 0.900 second using v1.01-cache-2.11-cpan-39bf76dae61 )