lash 0.1.1 → 1.0.1

data/.autotest

@@ -0,0 +1,10 @@
+Autotest.add_hook(:initialize) do |at|
+  at.clear_mappings
+  at.add_mapping(%r%^lib/(.*)\.rb$%) { |_, m|
+    ["spec/lib/#{m[1]}_spec.rb"]
+  }
+  at.add_mapping(%r%^spec/(models|controllers|routing|views|helpers|mailers|requests|lib)/.*rb$%) { |filename, _|
+    filename
+  }
+  nil
+end

data/.gitignore

@@ -4,4 +4,5 @@ Gemfile.lock
 pkg/*
 .yardoc
 doc/yard/
-.DS_Store
+.DS_Store
+/tmp/

data/.rspec

@@ -0,0 +1 @@
+--color --debug

data/Gemfile

@@ -1,4 +1,5 @@
 source "http://rubygems.org"
 
 # Specify your gem's dependencies in lash.gemspec
-gemspec
+gemspec
+

data/LICENSE.md

@@ -0,0 +1,48 @@
+# License Notices
+
+## Lash
+
+Copyright (C) 2011 Apps In Your Pants.
+
+Dual licensed under MIT and GPLv3
+
+
+## Google Closure Compiler
+
+Copyright 2009 The Closure Compiler Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+
+## Optipng
+
+Copyright (C) 2001-2011 Cosmin Truta.
+
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the author(s) be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software.  If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not
+   be misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.

data/README.md

@@ -15,10 +15,10 @@ Based on ["Optimizing asset bundling and serving with Rails"](https://github.com
 
   	# Gemfile
   	gem 'lash'
-  	
-or as a plugin
 
-    rails plugin install git://github.com/appsinyourpants/lash.git
+
+
+
 
 ## Bundling Assets
 
@@ -29,6 +29,10 @@ Lash includes several rake tasks to bundle loose, development versions of your s
 
 Individual assets can be bundled on demand using their respective `lash:asset_type` tasks.
 
+
+
+
+
 ## JavaScript
 
 Lash expects to find JavaScript assets as subfolders of the public/javascripts folder like so
@@ -60,6 +64,19 @@ __public/javascripts/demand__
 
 ### CDN JavaScripts and Developer Mode
 
+Shared CDN hosts are great for optimizing your site's user experience but there are two issues that developers regularly have to deal with - developing offline and accounting for CDN unavailability. Lash handles both of these cases with ease.
+
+During development, Lash will use the copies of the libraries found in your public/javascripts/cdn directory. This makes it easy to work offline.
+
+In production, Lash will use the CDN versions of the scripts and if a runtime test is provided, fallback to the local version if the CDN is unavailable.
+
+    <%= javascript_cdn 'jquery', '//ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js', 'jQuery' -%>
+   
+    # => <script src="//ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js" type="text/javascript"></script>
+    # => <script type="text/javascript">
+    # =>  if(typeof jQuery === "undefined" ) 
+    # =>    document.write( unescape("<script src=\"/javascripts/cdn/jquery.min.js?1297459967\" type=\"text/javascript\"><\/script>") );
+    # => </script>
 
 ### Referencing JavaScript Bundles in Layouts
 
@@ -72,9 +89,15 @@ When {Lash::BundleHelper#bundle_files?} is true (on by default in production), l
 
 See {Lash::BundleHelper#javascript_bundle} for details.
 
+### application.bundleVersion.js
 
+When referring to assets in your javascripts you loose the convenience of the rails cache busting asset tags. During bundling, lash will generate an `public/javascripts/application/application.bundleVersion.js` which gets bundled into the application script. This script simply declares a global variable `bundleVersion` which you can append to asset urls in your scripts.
 
-#### JavaScript bundling tasks
+#### Example
+  
+    $('#waiting-div').append( $('<img src="/images/wainting.gif?' + bundleVersion + '" />' ) )
+
+### JavaScript bundling tasks
 
     rake lash:js                    # Bundles and minifies javascripts
     rake lash:js_bundle             # Bundles javascripts folders into single minified files
@@ -84,8 +107,97 @@ See {Lash::BundleHelper#javascript_bundle} for details.
 
 
 
+
+
 ## CSS Sprites
 
+CSS sprites is are an effective optimization technique, but can be very time consuming to produce. Lash makes it easy. Just drop the desired images into a folder, run a rake task and you've got a highly optimized sprite image and accompanying CSS file.
+
+Lash looks for sprite images in `public/sprites`. Each sub folder will be bundled into a single image and css file. Given the following folder structure:
+
+* public/sprites/ui
+  * accept.png
+  * add.png
+  
+Lash will generate a sprite image `public/images/ui-sprite.png` and corresponding css file `public/stylesheets/sass/_ui-sprite.scss`.
+
+#### To generate your apps sprites
+
+    rake lash:sprites
+
+
+### _version.scss
+
+When referring to assets in your css scripts you loose the convenience of the rails cache busting asset tags. During bundling, lash will generate an `public/stylesheets/sass/_version.scss`. You can include this into any of your SASS scripts when you reference static assets like images. 
+
+#### Example
+
+    @import 'version';
+    .smiley { background-image: url(/images/smiley.png?#{$bundle-version})}
+
+### CSS bundling tasks
+
+    rake lash:css        # Process CSS scripts
+    rake lash:css_gzip   # Compresses stylesheets for use with nginx gzip_static
+    rake lash:sass       # Pre-generate sass scripts
+    rake lash:sprites    # Generate CSS sprites from the public/sprites folders
+
+
+
+
+
+## Optimizing PNG Images
+
+Most image editors will compress PNG files using a very basic compression algorithm. However the PNG format 
+allows for much more aggressive optimization at the cost of speed. Since image resources are some of the
+heaviest assets downloaded from your site, optimizing them is often worth the effort.
+
+See [A guide to PNG optimization](http://optipng.sourceforge.net/pngtech/optipng.html) for a more detailed discussion.
+
+#### To optimize your pngs
+
+    rake lash:png
+    
+    
+    
+    
+
 ## Integrating With Capistrano
 
- 
+Lash was designed to work with capistrano to easily run static asset bundling during the deployment process. This makes 
+sure that all assets are primed for static serving from your website without interfering with any existing requests
+that are currently being served.
+
+#### To run bundling tasks during deployment
+
+    # in config/deploy.rb
+    require 'lash/capistrano'
+ 
+If you use capistrano to publish your app (and really who isn't?) you'll want to add some additional filters to your .gitignore file
+
+    # lash asset helpers
+    public/javascripts/common/application.bundleVersion.js
+    public/stylesheets/sass/_version.scss
+    
+    # lash generated filed
+    public/javascripts/bundle_*.js
+    public/stylesheets/*.css
+    public/stylesheets/sass/_*-sprite.scss
+    public/javascripts/**/*.min.js
+ 
+
+
+
+
+
+
+ 
+## License
+
+### Lash
+
+Copyright (C) 2011 Apps In Your Pants.
+
+Dual licensed under MIT and GPLv3
+
+[Other License Notices](LICENSE.md)

data/Rakefile

@@ -1,2 +1,3 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
+

data/lib/lash.rb

@@ -3,17 +3,30 @@ module Lash
   # from the Lash::ViewHelpers.lash_options hash. You can write
   # to this hash to override default options on the global level:
   #
-  #   Lash::ViewHelpers.lash_options[:unicorns] = 'run free'
+  #     Lash.lash_options[:unicorns] = 'run free'
   #
   def self.lash_options() @lash_options; end
+
   # Overrides the default {lash_options}
-  def self.lash_options=(value) @lash_options = value; end
+  #
+  # @option options [String] :use_asset_servers           Use asset server subdomain hack to allow multiple simultaenous connections. See {Lash::AssetsHost.resolve_static_asset_server_for_source}.
+  # @option options [String] :use_asset_servers_in_ssl    Use asset server subdomain hack even over SSL. Requires a wildcard certificate.
+  # @option options [String] :use_sass                    Support SASS 
+  # @option options [String] :use_git_asset_id            Use GIT repro id for cachebusting asset id
+  # @option options [String] :closure_compiler            Path to custom version of google's closure compiler.
+  def self.lash_options=(options) @lash_options = options; end
   
   self.lash_options = {
     :use_asset_servers            => true,
     :use_asset_servers_in_ssl     => true,
-    :use_sass                     => Gem.available?('sass')
+    :use_sass                     => Gem.available?('sass'),
+    :use_git_asset_id             => true,
+    :closure_compiler             => File.expand_path( "../../bin/closure-compiler/compiler.jar", __FILE__ )
   }
 end
 
-require 'lash/railtie' if defined?(::Rails::Railtie)
+require 'lash/railtie' if defined?(Rails) && Rails === Class and defined?(::Rails::Railtie)
+require 'lash/java_script_bundler'
+require 'lash/sprite_bundler'
+require 'lash/files'
+require 'lash/assets_host'

data/lib/lash/assets_host.rb

@@ -0,0 +1,74 @@
+require 'grit'
+require 'lash'
+
+module Lash
+  module AssetsHost    
+    
+    # Configures Rails to use the most recent GIT repo id for public/(javascripts|stylesheets|images) for the
+    # asset id used for cache busting.
+    def self.use_git_asset_id
+      return unless Lash.lash_options[:use_git_asset_id]
+
+      repo = Grit::Repo.new( Rails.root.to_s )
+
+      ENV['RAILS_ASSET_ID'] = \
+      [:javascripts, :stylesheets, :images] \
+        .map { |folder| repo.log( 'master', "spec/test_app/public/#{folder}", :max_count => 1 ).first } \
+        .max_by { |log| log && log.committed_date } 
+        .id
+    end
+    
+    # Generates an asset id for the given file used for cache-busting
+    def self.asset_id( file )
+      if Lash.lash_options[:use_git_asset_id]
+        repo = Grit::Repo.new( Rails.root.to_s )
+        [:javascripts, :stylesheets, :images] \
+          .map { |folder| repo.log( 'master', "spec/test_app/public/#{folder}", :max_count => 1 ).first } \
+          .max_by { |log| log && log.committed_date } 
+          .id
+      elsif ::File.exist?( file )
+        File.mtime( file ).to_i.to_s
+      end
+    end
+    
+    # Method used to map an asset to a static asset server. This method simply generates a semi-random domain
+    # prefix based on the filename of the source. The asset server should resolve to the same server as
+    # the rails app. This is a basic browser hack to allow more than 4 connections to the server so that the
+    # browser can download multiple assets simultaneously.
+    #   
+    # @example 
+    #     request.host        # => lvh.me
+    #     resolve_static_asset_server_for_source "smiles", request
+    #                         # => assets1.lvh.me      
+    #
+    #     # from terminal
+    #     nslookup lvh.me           # => 127.0.0.1
+    #     nslookup assets1.lvh.me   # => 127.0.0.1
+    
+    def self.resolve_static_asset_server_for_source( source, request )
+        if /\/\// =~ source
+          nil
+        elsif request.ssl? and ! Lash.lash_options[:use_asset_servers_in_ssl]
+          nil
+        elsif !Lash.lash_options[:use_asset_servers]
+          nil
+        else
+
+          # Change the host name to include a randomized asset name at the same domain
+          # level. This is required so that HTTPS requests can use a wildcard domain
+          # without using subject alt name.
+
+          host = request.host_with_port
+          parts = host.split( /\./ )
+          if parts.length > 2 
+            parts[0] = "#{parts[0]}-assets#{source.hash % 4}"
+          else
+            parts.unshift "assets#{source.hash % 4}"
+          end
+
+          "http#{'s' if request.ssl?}://#{parts.join('.')}"
+        end
+      end
+
+  end
+end

data/lib/lash/bundle_helper.rb

@@ -1,20 +1,19 @@
-require 'find'
+require 'lash/files'
 
 module Lash
   module BundleHelper
     
-    unloadable if Rails.env.development?
-    
     # Root folder where application javascript files can be found
     def javascript_root
        File.join( ::Rails.root, 'public', 'javascripts', '' )
     end
 
     # Determines if the processed bundle files should be used, or the loose files used to build those bundles.
-    # By default bundled fies are used in production or if the request includes a `:bundle` param or cookie.
+    # By default bundled files are used in production or if the request includes a `:bundle` param or cookie.
+    # @return [Boolean] true if bundled assets should be used.
     def bundle_files?
       if params.has_key? :bundle
-        return params[:bundle] =~ /^t(rue)?|y(es)?|1$/i
+        return /^t(rue)?|y(es)?|1$/i.match( params[:bundle] ) != nil
       end
       Rails.env.production? || cookies[:bundle] == "yes"
     end
@@ -71,28 +70,11 @@ module Lash
     end
 
     private
-      # Collects an array of all files in `{basedir}` with the given `{ext}`.
-      def recursive_file_list( basedir, ext )
-        files = []
-        return files unless File.exist? basedir
-        Find.find( basedir ) do |path|
-          if FileTest.directory?( path )
-            if File.basename( path )[0] == ?. # Skip dot directories
-              Find.prune
-            else
-              next
-            end
-          end
-          files << path if File.extname( path ) == ext
-        end
-        files.sort
-      end
-
       # Generates javscript include tags for the actual bundled javascript for each named bundle
       def javascript_include_bundles( bundles )
         output = ""
         bundles.each do |bundle|
-          output << javascript_src_tag( "bundle_#{bundle}", {} )
+          output << javascript_src_tag( "bundle_#{bundle}.js", {} )
         end
         output.html_safe
       end
@@ -101,7 +83,7 @@ module Lash
       def javascript_include_files( bundles )
         output = "\n"
         bundles.each do |bundle|
-          files = recursive_file_list( File.join( javascript_root, bundle ), '.js' )
+          files = Lash::Files.recursive_file_list( File.join( javascript_root, bundle ), '.js' )
           files.each do |file|
             file = file.gsub( javascript_root, '' )
             output << javascript_src_tag( file, {} ) + "\n" 

data/lib/lash/capistrano.rb

@@ -1,3 +1,5 @@
+# Adds a deployment task to automatically generate bundled assetes on the server during deployment
+
 Capistrano::Configuration.instance.load do
   namespace :deploy do
     task :lash, :roles => [:app], :except => { :no_release => true } do

data/lib/lash/closure_minifier.rb

@@ -0,0 +1,20 @@
+require 'lash/java_script_minifier'
+
+module Lash
+  # Minifies a collection of scripts using Google's closure compiler.
+  class ClosureMinifier < JavaScriptMinifier
+    
+    private 
+      def minify_scripts( files, target )
+        tmp = "#{target}.tmp"
+        `java -jar \"#{Lash.lash_options[:closure_compiler]}\" #{command_options} --warning_level QUIET --js \"#{files.join("\" --js \"")}\" --js_output_file \"#{tmp}\"`
+        if $?.exitstatus == 0   
+          File.delete target if File.exist? target
+          File.rename tmp, target
+        end        
+      ensure
+        File.delete tmp if File.exist? tmp
+      end
+    
+  end
+end

data/lib/lash/files.rb

@@ -0,0 +1,56 @@
+require 'find'
+
+module Lash
+  module Files
+  
+    # Collects an array of all files in {basedir} with the given ext.
+    #
+    # @param [String] basedir the root directory to search
+    # @param [String] ext extension to filter results by
+    # @return [Array] an array of expanded paths for each file in {basedir} and any of it's sub directories
+    def self.recursive_file_list( basedir, ext )
+      unless ext.is_a? Regexp
+        ext = ".#{ext}" if ext && ext[0] != ?.
+        ext ||= ""
+      end
+      
+      files = []
+      return files unless File.exist? basedir
+      Find.find( basedir ) do |path|
+        if FileTest.directory?( path )
+          if File.basename( path )[0] == ?. # Skip dot directories
+            Find.prune
+          else
+            next
+          end
+        end
+        if ext.is_a? Regexp
+          files << path if ext.match( path )
+        else
+          files << path if File.extname( path ) == ext
+        end
+      end
+      files.sort
+    end
+    
+    # Gets all the top level directories in the given base_path
+    #
+    # @param [String] basedir the root directory to search
+    # @return [Array] an array of expanded paths for all directories found
+    def self.get_top_level_directories( basedir )
+      Dir.entries( basedir ).collect do |path|
+        path = File.join( basedir, path )
+        File.basename( path )[0] == ?. || !File.directory?( path ) ? nil : path # not dot directories or files
+      end - [nil]
+    end
+    
+    # Gets the relative path from root to path of path is a subdirectory of root, otherwise returns path
+    def self.relative_to( path, root )
+      path = File.expand_path( path )
+      root = File.expand_path( root )
+      return path unless path.start_with? root
+      path[ root.length + 1, path.length ]
+    end
+    
+  end
+end