fingerprintless-assets 1.0.pre

data/README.md

@@ -0,0 +1,44 @@
+Fingerprintless Assets
+======================
+
+The asset pipeline is a great new component of Rails 3.1. However it has a feature known as fingerprinting that makes it impossible to properly incorporate many popular JavaScript libraries (including [TinyMCE](http://tinymce.moxiecode.com/), [CKEditor](http://ckeditor.com/) and [FancyZoom](https://github.com/jnunemaker/fancy-zoom) to name just a few) into the asset pipeline.
+
+This gem patches the asset pipeline to allow these libraries to be used, by disabling the fingerprinting functionality for specific files or paths.
+
+
+Installation & Usage
+--------------------
+
+Add the following line to your Gemfile and run `bundle install`:
+
+    gem 'fingerprintless-assets'
+
+The `fingerprintless-assets` gem does not change any fingerprinting options by default but allows you to set the following options in your application configuration:
+
+    # Disable asset fingerprinting entirely
+    config.assets.fingerprinting.enabled = false
+
+    # or exclude specific assets from fingerprinting (use a path, glob or regex)
+    config.assets.fingerprinting.exclude << "nofingerprints/*"
+
+Rails plugins can require this gem and set these options in an initializer, making the whole process transparent to the end-developer. See the [tinymce-rails](https://github.com/spohlenz/tinymce-rails) project for an example of this.
+
+
+The Problem With Fingerprinting
+-------------------------------
+
+Fingerprinting is used to improve caching of assets by including a version-specific fingerprint in the asset filename. From the [Asset Pipeline Rails Guide](http://ryanbigg.com/guides/asset_pipeline.html#what-is-fingerprinting-and-why-should-i-care):
+
+> When a filename is unique and based on its content, http headers can be set to encourage caches everywhere (at ISPs, in browsers) to keep there own copy of the content. When the content is updated, the fingerprint will change and the remote clients will request the new file. This is generally known as cachebusting.
+
+In the Rails asset pipeline (in production mode), the MD5 hash of the file contents is inserted into the filename, e.g. `application-d41d8cd98f00b204e9800998ecf8427e.js`. This requires that the relevant `asset_url` helpers are used when referencing assets in your HTML, JavaScript or CSS (or CoffeeScript, SASS, etc).
+
+When adding third-party code to your application, it is not always practical to make these changes. Worse still, more advanced libraries like TinyMCE load in plugins and other assets dynamically, making these changes virtually impossible. In these situations, the third-party code will work fine whilst in development but break suddenly when deployed to production.
+
+One option is to move the assets into the `public` directory. Whilst this approach will work, it has some major drawbacks:
+
+1. It prevents you from using the other great features of the asset pipeline such as asset concatenation and minification.
+2. It leaves your assets scattered across multiple locations, making maintenance difficult.
+3. A gem that provides assets must provide an additional rake task to copy its assets into `public`.
+
+Asset fingerprinting is a great feature and it is recommended you use it wherever possible. However without this gem, it is impossible to disable it for those libraries that are incompatible.

data/lib/fingerprintless-assets.rb

@@ -0,0 +1,11 @@
+require "sprockets"
+require 'sprockets/base'
+
+require "fingerprintless_assets/monkey_patches/configuration"
+require "fingerprintless_assets/monkey_patches/environment"
+require "fingerprintless_assets/monkey_patches/index"
+require "fingerprintless_assets/monkey_patches/server"
+require "fingerprintless_assets/monkey_patches/static_compilation"
+require "fingerprintless_assets/monkey_patches/utils"
+
+require "fingerprintless_assets/railtie" if defined?(Rails)

data/lib/fingerprintless_assets/monkey_patches/configuration.rb

@@ -0,0 +1,38 @@
+module FingerprintlessAssets
+  module Configuration
+    # Checks if asset path fingerprinting is enabled.
+    def fingerprinting_enabled?
+      @fingerprinting_enabled
+    end
+
+    # Enable or disable asset path fingerprinting.
+    def fingerprinting_enabled=(enabled)
+      @fingerprinting_enabled = enabled
+    end
+
+    # Returns an `Array` of paths, globs or `Regexp`s that
+    # should be excluded from asset path fingerprinting.
+    def fingerprinting_exclusions
+      @fingerprinting_exclusions ||= []
+    end
+
+    # Set the paths that should be excluded from asset path fingerprinting.
+    def fingerprinting_exclusions=(exclusions)
+      @fingerprinting_exclusions = exclusions
+    end
+
+    # Checks if the path should be fingerprinted.
+    def fingerprint_path?(logical_path)
+      fingerprinting_enabled? && !exclude_path_from_fingerprinting?(logical_path)
+    end
+
+  private
+    # Checks if the given path is in the current list
+    # of fingerprinting exclusions.
+    def exclude_path_from_fingerprinting?(logical_path)
+      fingerprinting_exclusions.any? { |path| match_path?(logical_path, path) }
+    end
+  end
+end
+
+Sprockets::Base.send(:include, FingerprintlessAssets::Configuration)

data/lib/fingerprintless_assets/monkey_patches/environment.rb

@@ -0,0 +1,12 @@
+Sprockets::Environment.class_eval do
+  alias_method :original_initialize, :initialize
+  
+  def initialize(root = '.')
+    original_initialize(root)
+
+    # Enable fingerprinting by default
+    @fingerprinting_enabled = true
+    
+    yield self if block_given?
+  end
+end

data/lib/fingerprintless_assets/monkey_patches/index.rb

@@ -0,0 +1,11 @@
+Sprockets::Index.class_eval do
+  alias_method :original_initialize, :initialize
+  
+  def initialize(environment)
+    original_initialize(environment)
+
+    # Inherit fingerprinting values from environment
+    @fingerprinting_enabled    = environment.fingerprinting_enabled?
+    @fingerprinting_exclusions = environment.fingerprinting_exclusions
+  end
+end

data/lib/fingerprintless_assets/monkey_patches/server.rb

@@ -0,0 +1,9 @@
+module FingerprintlessAssets
+  module Server
+    def path(logical_path, _ignored_fingerprint = true, prefix = nil)
+      super(logical_path, fingerprint_path?(logical_path), prefix)
+    end
+  end
+end
+
+Sprockets::Base.send(:include, FingerprintlessAssets::Server)

data/lib/fingerprintless_assets/monkey_patches/static_compilation.rb

@@ -0,0 +1,38 @@
+module FingerprintlessAssets
+  module StaticCompilation
+    def precompile(*paths)
+      raise "missing static root" unless static_root
+
+      paths.each do |path|
+        files.each do |logical_path|
+          next unless match_path?(logical_path, path)
+          
+          if asset = find_asset(logical_path)
+            precompile_asset(asset)
+          end
+        end
+      end
+    end
+    
+    def precompile_asset(asset)
+      if fingerprint_path?(asset.logical_path)
+        attributes  = attributes_for(asset.logical_path)
+        digest_path = attributes.path_with_fingerprint(asset.digest)
+        filename    = static_root.join(digest_path)
+      else
+        filename    = static_root.join(asset.logical_path)
+      end
+
+      # Ensure directory exists
+      FileUtils.mkdir_p filename.dirname
+
+      # Write file
+      asset.write_to(filename)
+
+      # Write compressed file if its a bundled asset like .js or .css
+      asset.write_to("#{filename}.gz") if asset.is_a?(Sprockets::BundledAsset)
+    end
+  end
+end
+
+Sprockets::Base.send(:include, FingerprintlessAssets::StaticCompilation)

data/lib/fingerprintless_assets/monkey_patches/utils.rb

@@ -0,0 +1,15 @@
+module FingerprintlessAssets
+  module Utils
+    def match_path?(path, match)
+      if match.is_a?(Regexp)
+        # Match path against `Regexp`
+        match.match(path)
+      else
+        # Otherwise use fnmatch glob syntax
+        File.fnmatch(match.to_s, path)
+      end
+    end
+  end
+end
+
+Sprockets::Base.send(:include, FingerprintlessAssets::Utils)

data/lib/fingerprintless_assets/railtie.rb

@@ -0,0 +1,21 @@
+module FingerprintlessAssets
+  class Railtie < ::Rails::Railtie
+    initializer :setup_configuration, :before => :load_environment_config do |app|
+      app.config.assets.fingerprinting = ActiveSupport::OrderedOptions.new
+      app.config.assets.fingerprinting.exclude = []
+    end
+
+    initializer :set_configuration_defaults do |app|
+      # Unless explicitly set, enable fingerprinting if performing caching
+      unless app.config.assets.fingerprinting.key?(:enabled)
+        app.config.assets.fingerprinting.enabled = app.config.action_controller.perform_caching
+      end
+    end
+    
+    config.after_initialize do |app|
+      # Apply configuration to the application's asset environment
+      app.assets.fingerprinting_enabled    = app.config.assets.fingerprinting.enabled
+      app.assets.fingerprinting_exclusions = app.config.assets.fingerprinting.exclude
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: fingerprintless-assets
+version: !ruby/object:Gem::Version
+  version: 1.0.pre
+  prerelease: 4
+platform: ruby
+authors:
+- Sam Pohlenz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-03 00:00:00.000000000 +09:30
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sprockets
+  requirement: &2153060000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.0.beta.12
+  type: :runtime
+  prerelease: false
+  version_requirements: *2153060000
+description: Adds asset fingerprinting configuration options to Rails and Sprockets
+  so that paths can be excluded from fingerprinting.
+email: sam@sampohlenz.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/fingerprintless-assets.rb
+- lib/fingerprintless_assets/monkey_patches/configuration.rb
+- lib/fingerprintless_assets/monkey_patches/environment.rb
+- lib/fingerprintless_assets/monkey_patches/index.rb
+- lib/fingerprintless_assets/monkey_patches/server.rb
+- lib/fingerprintless_assets/monkey_patches/static_compilation.rb
+- lib/fingerprintless_assets/monkey_patches/utils.rb
+- lib/fingerprintless_assets/railtie.rb
+has_rdoc: true
+homepage: 
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Fingerprinting controls for the Rails 3.1 asset pipeline.
+test_files: []