asset_hat 0.1.5 → 0.2.0

data/lib/asset_hat.rb

@@ -2,19 +2,66 @@
   require File.join(File.dirname(__FILE__), 'asset_hat', x)
 end
 
+# 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
+#
+# See README.rdoc for more.
 module AssetHat
-  RAILS_ROOT      = File.join(File.dirname(__FILE__), '..') unless defined?(RAILS_ROOT)
-  TYPES           = [:css, :js]
-  ASSETS_DIR      = defined?(Rails.public_path) ? Rails.public_path : 'public'
-  JAVASCRIPTS_DIR = "#{ASSETS_DIR}/javascripts"
+  RAILS_ROOT = File.join(File.dirname(__FILE__), '..') unless defined?(RAILS_ROOT) #:nodoc:
+
+  # Types of supported assets; currently <code>[:css, :js]</code>.
+  TYPES = [:css, :js]
+
+  # Base directory in which all assets are kept, e.g., 'public/'.
+  ASSETS_DIR = defined?(Rails.public_path) ? Rails.public_path : 'public'
+
+  # Directory in which all stylesheets are kept, e.g., 'public/stylesheets/'.
   STYLESHEETS_DIR = "#{ASSETS_DIR}/stylesheets"
+
+  # Directory in which all JavaScripts are kept, e.g., 'public/javascripts/'.
+  JAVASCRIPTS_DIR = "#{ASSETS_DIR}/javascripts"
+
+  # Relative path for the config file.
   RELATIVE_CONFIG_FILEPATH = File.join('config', 'assets.yml')
+
+  # Absolute path for the config file.
   CONFIG_FILEPATH = File.join(RAILS_ROOT, RELATIVE_CONFIG_FILEPATH)
 
   class << self
-    attr_accessor :config, :asset_exists, :html_cache
+    attr_accessor :config, :asset_exists, :html_cache #:nodoc:
   end
 
+  # Nested-hash version of <code>config/assets.yml</code>.
   def self.config
     if !cache? || @config.blank?
       @config = YAML.load(File.open(CONFIG_FILEPATH, 'r'))
@@ -22,6 +69,9 @@ module AssetHat
     @config
   end
 
+  # Argument: <code>:css</code> or <code>:js</code>
+  #
+  # Returns the path to the directory where CSS or JS files are stored.
   def self.assets_dir(type)
     case type.to_sym
     when :css ; STYLESHEETS_DIR
@@ -30,6 +80,15 @@ module AssetHat
     end
   end
 
+  # Returns true if the specified asset exists in the file system:
+  #
+  #     AssetHat.asset_exists?('application', :css)
+  #       # => true if /public/stylesheets/application.css exists
+  #     AssetHat.asset_exists?('some-plugin', :js)
+  #       # => true if /public/javascripts/some-plugin.js exists
+  #
+  # See also <code>AssetHat::STYLESHEETS_DIR</code> and
+  # <code>AssetHat::JAVASCRIPTS_DIR</code>.
   def self.asset_exists?(filename, type)
     # Process arguments
     type = type.to_sym
@@ -48,20 +107,31 @@ module AssetHat
     @asset_exists[type][filename]
   end
 
+  # Returns <code>true</code> if bundles should be included as single minified
+  # files (e.g., in production), or <code>false</code> if bundles should be
+  # included as separate, unminified files (e.g., in development). To modify
+  # this value, set <code>config.action_controller.perform_caching = true</code>
+  # in your environment.
   def self.cache? ; ActionController::Base.perform_caching ; end
 
+  # Returns the expected path for the minified version of an asset:
+  #
+  #     AssetHat.min_filepath('public/stylesheets/bundles/application.css', 'css')
+  #       # => 'public/stylesheets/bundles/application.min.css'
+  #
+  # See also <code>AssetHat::CSS.min_filepath</code> and
+  # <code>AssetHat::JS.min_filepath</code>.
   def self.min_filepath(filepath, extension)
     filepath.sub(/([^\.]*).#{extension}$/, "\\1.min.#{extension}")
   end
 
+  # Returns the extension-less names of files in the given bundle:
+  #
+  #     AssetHat.bundle_filenames('application', :css)
+  #       # => ['reset', 'application', 'clearfix']
+  #     AssetHat.bundle_filenames('non-existent-file', :css)
+  #       # => nil
   def self.bundle_filenames(bundle, type)
-    # Usage:
-    #
-    #     AssetHat.bundle_filenames('application', :css)
-    #       # => ['reset', 'application', 'clearfix']
-    #     AssetHat.bundle_filenames('non-existent-file', :css)
-    #       # => nil
-
     # Process arguments
     unless TYPES.include?(type.to_sym)
       raise "Unknown type \"#{type}\"; should be one of: #{TYPES.join(', ')}."
@@ -71,14 +141,15 @@ module AssetHat
     self.config[type.to_s]['bundles'][bundle] rescue nil
   end
 
+  # Returns the full paths of files in the given bundle:
+  #
+  #     AssetHat.bundle_filenames('application', :css)
+  #       # => ['/path/to/app/public/stylesheets/reset.css',
+  #             '/path/to/app/public/stylesheets/application.css',
+  #             '/path/to/app/public/stylesheets/clearfix.css']
+  #     AssetHat.bundle_filenames('non-existent-file', :css)
+  #       # => nil
   def self.bundle_filepaths(bundle, type)
-    # Usage:
-    #
-    #     AssetHat.bundle_filenames('application', :css)
-    #       # => ['reset', 'application', 'clearfix']
-    #     AssetHat.bundle_filenames('non-existent-file', :css)
-    #       # => nil
-
     # Process arguments
     unless TYPES.include?(type.to_sym)
       raise "Unknown type \"#{type}\"; should be one of: #{TYPES.join(', ')}."
@@ -91,4 +162,8 @@ module AssetHat
       filenames.map { |fn| File.join(dir, "#{fn}.#{type}") } : nil
   end
 
+  def self.clear_html_cache
+    html_cache = {}
+  end
+
 end

data/tasks/asset_hat.rake

@@ -1 +1 @@
-require File.join(File.dirname(__FILE__), %w[.. lib asset_hat tasks])
+require 'asset_hat/tasks'

data/test/asset_hat_helper_test.rb

@@ -124,20 +124,74 @@ class AssetHatHelperTest < ActionView::TestCase
           assert_equal js_tag("jquery.some-plugin.min.js?#{@commit_id}"), output
         end
 
-        should 'include jQuery' do
-          version = AssetHat::JS::Vendors::JQUERY_DEFAULT_VERSION
-          output = include_js(:jquery, :cache => true)
-          assert_equal(
-            js_tag("jquery-#{version}.min.js?#{@commit_id}"), output)
-        end
-
-        should 'include jQuery by version' do
-          version = '1.3.2'
+        context 'with vendors' do
+          should 'know where to find each vendor file' do
+            AssetHat::JS::VENDORS.each do |vendor|
+              assert include_js(vendor, :cache => true).present?
+            end
+          end
+
+          should 'include jQuery and jQuery UI' do
+            flexmock(AssetHat).should_receive(:config => @original_config)
+            [:jquery, :jquery_ui].each do |vendor|
+              output = include_js(vendor, :cache => true)
+              assert_equal js_tag("#{vendor.to_s.dasherize}.min.js?#{@commit_id}"), output
+            end
+          end
+
+          should 'include Prototype and script.aculo.us' do
+            [:prototype, :scriptaculous].each do |vendor|
+              output = include_js(vendor, :cache => true)
+              assert_equal js_tag("#{vendor}.js?#{@commit_id}"), output
+                # N.B.: Including only the regular, not minified, version
+            end
+          end
+        end # context 'with vendor JS'
+
+        should 'include jQuery by version via helper option' do
+          version = '1.4.1'
           output = include_js(:jquery, :version => version, :cache => true)
           assert_equal(
             js_tag("jquery-#{version}.min.js?#{@commit_id}"), output)
         end
 
+        context 'with a mock config' do
+          setup do
+            version = '1.4.1'
+            config = AssetHat.config
+            config['js']['vendors'] = {
+              'jquery' => {
+                'version' => version,
+                'remote_url' => 'http://example.com/cdn/jquery.min.js'
+              }
+            }
+            flexmock(AssetHat).should_receive(:config => config)
+          end
+
+          should 'include jQuery by version via config file' do
+            version = AssetHat.config['js']['vendors']['jquery']['version']
+            assert_equal(
+              js_tag("jquery-#{version}.min.js?#{@commit_id}"),
+              include_js(:jquery, :cache => true)
+            )
+          end
+
+          context 'with remote requests' do
+            setup do
+              flexmock(ActionController::Base).should_receive(
+                :consider_all_requests_local => false)
+            end
+
+            should 'use specified remote URL for jQuery' do
+              src = AssetHat.config['js']['vendors']['jquery']['remote_url']
+              assert_equal(
+                %Q{<script src="#{src}" type="text/javascript"></script>},
+                include_js(:jquery, :cache => true)
+              )
+            end
+          end # context 'with remote requests'
+        end # context 'with a mock config'
+
         should 'include multiple files by name' do
           flexmock(AssetHat).should_receive(:asset_exists?).and_return(true)
           expected = %w[foo jquery.bar].map do |source|

data/test/test_helper.rb

@@ -22,10 +22,14 @@ unless defined?(Rails)
   end
 end
 
+@original_config = AssetHat.config
+  # Use this when FlexMock refuses to teardown automatically. (Yes,
+  # this is ugly.)
+
 class ActionView::TestCase
   teardown :clear_html_cache
 
   def clear_html_cache
-    AssetHat.html_cache = {}
+    AssetHat.clear_html_cache
   end
 end

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: asset_hat
 version: !ruby/object:Gem::Version 
-  version: 0.1.5
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Ron DeVera
@@ -10,49 +15,79 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-11 00:00:00 -05:00
+date: 2010-06-10 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: shoulda
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  name: flexmock
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.10.2
-    version: 
+        segments: 
+        - 0
+        - 8
+        - 6
+        version: 0.8.6
+  type: :development
+  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: flexmock
+  name: hanna
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 1
+        - 12
+        version: 0.1.12
   type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.8.6
-    version: 
+        segments: 
+        - 2
+        - 10
+        - 2
+        version: 2.10.2
+  type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: cssmin
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 2
         version: 1.0.2
-    version: 
+  type: :runtime
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: jsmin
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 0
+        - 1
         version: 1.0.1
-    version: 
+  type: :runtime
+  version_requirements: *id005
 description: Minify, bundle, and optimize CSS/JS assets.
 email: ronald.devera@gmail.com
 executables: []
@@ -61,21 +96,52 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.markdown
+- README.rdoc
 files: 
 - .gitignore
 - HISTORY
 - LICENSE
-- README.markdown
+- README.rdoc
 - Rakefile
 - VERSION.yml
 - app/helpers/asset_hat_helper.rb
 - asset_hat.gemspec
 - config/assets.yml
+- doc/classes/AssetHat.html
+- doc/classes/AssetHat/CSS.html
+- doc/classes/AssetHat/CSS/Engines.html
+- doc/classes/AssetHat/JS.html
+- doc/classes/AssetHat/JS/Engines.html
+- doc/classes/AssetHat/JS/Vendors.html
+- doc/classes/AssetHatHelper.html
+- doc/created.rid
+- doc/files/HISTORY.html
+- doc/files/LICENSE.html
+- doc/files/README_rdoc.html
+- doc/files/app/helpers/asset_hat_helper_rb.html
+- doc/files/lib/asset_hat/capistrano_rb.html
+- doc/files/lib/asset_hat/css_rb.html
+- doc/files/lib/asset_hat/js/vendors_rb.html
+- doc/files/lib/asset_hat/js_rb.html
+- doc/files/lib/asset_hat/tasks/css_rb.html
+- doc/files/lib/asset_hat/tasks/js_rb.html
+- doc/files/lib/asset_hat/tasks_rb.html
+- doc/files/lib/asset_hat/vcs_rb.html
+- doc/files/lib/asset_hat/version_rb.html
+- doc/files/lib/asset_hat_rb.html
+- doc/fr_class_index.html
+- doc/fr_file_index.html
+- doc/fr_method_index.html
+- doc/index.html
+- doc/rdoc-style.css
 - lib/asset_hat.rb
+- lib/asset_hat/capistrano.rb
 - lib/asset_hat/css.rb
 - lib/asset_hat/js.rb
+- lib/asset_hat/js/vendors.rb
 - lib/asset_hat/tasks.rb
+- lib/asset_hat/tasks/css.rb
+- lib/asset_hat/tasks/js.rb
 - lib/asset_hat/vcs.rb
 - lib/asset_hat/version.rb
 - public/javascripts/bundles/js-bundle-1.min.js
@@ -120,18 +186,20 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Your assets are covered.

data/README.markdown

@@ -1,154 +0,0 @@
-AssetHat
-========
-Your assets are covered.
-
-* Minify CSS and JS with one command. (Can be done on deploy instead of
-  at runtime.)
-* Bundle CSS and JS to reduce HTTP requests.
-* Reuse CSS and JS bundles across layouts without repetition.
-* Bust image caches by changing CSS URLs whenever an image is modified.
-* Force image URLs in your CSS to use CDN subdomains, not just the current
-  host.
-
-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
-
-Works with Rails 2.3.4 and above.
-
-
-
-Installation
-------------
-
-1. Install the gem:
-
-        gem install asset_hat
-
-2. Configure the gem:
-
-    * Using [Bundler](http://github.com/wycats/bundler):
-
-        1.  Add to your app's Gemfile: `gem 'asset_hat', '0.x.x'`
-
-        2.  Command-line: `gem bundle`
-
-    * Using Rails' `config.gem`, add to your app's `config/environment.rb`:
-
-        `config.gem 'asset_hat', :version => '0.x.x'`
-
-3. In your app, create `lib/tasks/asset_hat.rake` with the following contents:
-
-        begin
-          require 'asset_hat/tasks'
-        rescue LoadError
-          puts "Could not load AssetHat tasks: 'asset_hat' not found."
-        end
-
-
-
-Configuration
--------------
-
-1.  Create the default config file:
-
-        rake asset_hat:config
-
-2.  In your app, open the new config file at `config/assets.yml`, 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 `config/assets.yml`,
-    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 `public/stylesheets/bundles/` and
-    `public/javascripts/bundles/`. Your original CSS/JS files remain intact.
-
-4.  Set your deployment script to run `rake asset_hat:minify` after deploying
-    your latest CSS/JS. This overwrites previously minified bundles, and
-    leaves your original CSS/JS files intact.
-
-### Advanced configuration ###
-
-Additional settings are supported in `config/assets.yml`:
-
-* `engine`: Indicates how CSS and JS are minified; omit this setting to use
-  the defaults. If the default engines cause problems by minifying too
-  strongly, try switching each to `weak`. The `weak` engines are much safer,
-  but don't save as many bytes.
-
-* `vendors`: 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' %>
-
-**Use these:**
-
-    <%= 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>
-
-If your environment has `config.action_controller.perform_caching` set to
-`true` (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 `config/assets.yml`.
-
-### 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 `<link>` or
-`<script>` 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.