= AssetHat

Your assets are covered.

With Rails' default asset caching, CSS and JS are concatenated (not even
minified) the first time that bundle is requested. Not good enough. AssetHat
can automatically:

* Easily *minify* and *bundle* CSS and JS on deploy to reduce file sizes and
  HTTP requests.
* Load popular <strong>third-party JS</strong> (like jQuery and Prototype)
  from {<strong>Google's CDN</strong>}[http://code.google.com/apis/ajaxlibs/]
  when in production, or from localhost in development.
* Force image URLs in your CSS to use <strong>CDN subdomains</strong>, not
  just the current host.
* Add an image's last Git[http://git-scm.com/] commit ID to its CSS URLs to
  <strong>bust browser caches</strong> (e.g.,
  <code>/images/foo.png?ab12cd34e</code>).

After setup, you can use these in your layouts and views:

    <%= include_css :bundle => 'application' %>
      # => <link href="/stylesheets/bundles/application.min.css"
      #          media="screen,projection" rel="stylesheet" type="text/css" />

    <%= include_js :bundles => ['plugins', 'common'] %>
      # => <script src="/javascripts/bundles/plugins.min.js"
      #            type="text/javascript"></script>
      #    <script src="/javascripts/bundles/common.min.js"
      #            type="text/javascript"></script>

And this in your deploy script:

    rake asset_hat:minify

Tested with Rails 2.3.x.



== Installation

1.  Install the gem:

      gem install asset_hat

2.  Configure the gem:

    * If you're using {Bundler 0.9+}[http://github.com/carlhuda/bundler]:

      1.  Add to your app's Gemfile: <code>gem 'asset_hat', '0.x.x'</code>
      2.  Command-line: <code>bundle install</code>

    * If you're using Rails' <code>config.gem</code>, add to your app's
      <code>config/environment.rb</code>:

        config.gem 'asset_hat', :version => '0.x.x'

3.  Add to your app's Rakefile:

      require 'asset_hat/tasks'



== Configuration

1.  Create the default config file:

        rake asset_hat:config

2.  In your app, open the new file at <code>config/assets.yml</code>, and set
    up your CSS/JS bundles according to that file's example.

3.  Minify your bundles:

        rake asset_hat:minify

    This minifies all of the CSS/JS files listed in
    <code>config/assets.yml</code>, concatenates the minified code into bundle
    files, and adds CDN asset hosts and cache-busting commit IDs to image URLs
    in your CSS.

    Bundles are created as new files in
    <code>public/stylesheets/bundles/</code> and
    <code>public/javascripts/bundles/</code>. Your original CSS/JS files
    remain intact.

4.  Set your deployment script to run <code>rake asset_hat:minify</code> after
    deploying your latest CSS/JS. This overwrites previously minified bundles,
    and leaves your original CSS/JS files intact.

=== Advanced configuration

If you manage deployments with Capistrano[http://www.capify.org/], see the
gem's packaged example at <code>lib/asset_hat/capistrano.rb</code>.

Additional settings are supported in <code>config/assets.yml</code>:

* <code>engine</code>: Indicates how CSS and JS are minified; omit this
  setting to use the defaults. By default, CSS is minified with
  rgrove/cssmin[http://github.com/rgrove/cssmin] (a Ruby port of Lecomte's
  YUI Compressor and Schlueter's PHP cssmin), and JS is minified with
  rgrove/jsmin[http://github.com/rgrove/jsmin] (a Ruby port of Crockford's
  JSMin).

  If the default engines cause problems by minifying too
  strongly, try switching each to <code>weak</code>. The <code>weak</code>
  engines are much safer, but don't save as many bytes.

* <code>vendors</code>: Currently only allows for setting the jQuery version
  number:

        js:
          vendors:
            jquery:
              version: 1.4

  In the future, this will be used for configuring the retrieval of other
  third-party code.



== Usage

In your layouts and views, instead of these:

    <%= stylesheet_link_tag 'reset', 'application', 'clearfix',
                            :media => 'screen,projection',
                            :cache => 'bundles/application' %>
    <%= javascript_include_tag 'plugin-1', 'plugin-2', 'plugin-3',
                               :cache => 'bundles/application' %>

<strong>Use these:</strong>

    <%= include_css :bundle => 'application' %>
    <%= include_js  :bundle => 'application' %>

These turn into:

    <link href="/stylesheets/bundles/application.min.css"
      media="screen,projection" rel="stylesheet" type="text/css" />
    <script src="/javascripts/bundles/application.min.js"
      type="text/javascript"></script>

Have an enormous app? You can integrate gradually, using AssetHat alongside
Rails' default asset caching.

If your environment has <code>config.action_controller.perform_caching</code>
set to <code>true</code> (e.g., in production), the layout/view will include
minified bundle files. Otherwise, the separate, unminified files will be
included, based on the bundle contents you define in
<code>config/assets.yml</code>.

=== Advanced usage

You can also include single files as expected:

    <%= include_css 'reset', 'application' %>
    <%= include_js  'plugin.min', 'application' %>

Or include multiple bundles at once:

    <%= include_js :bundles => %w[plugins common] %>

When including multiple bundles at once, this yields one
<code><link></code> or <code><script></code> element per bundle.

You may want to use multiple bundles to separate plugins (rarely changed) from
application code (frequently changed). If all code is in one huge bundle, then
whenever there's a change, browsers have to re-download the whole bundle. By
using multiple bundles based on change frequency, browsers cache the rarely
changed code, and only re-download the frequently changed code.