dynamic_assets 0.1.0

data/README.rdoc

@@ -0,0 +1,225 @@
+= dynamic_assets
+
+DynamicAssets allows a Rails 3.0 app to serve its JavaScript and CSS assets
+dynamically instead of statically, which makes all kinds of things possible.
+Out of the box it can (optionally):
+
+* Combine all CSS files into one for faster downloading.
+* Combine all JavaScript files into one.
+* Minify assets to make them smaller.
+* Run your CSS or JS assets through ERB, like views.
+* Run your CSS assets through a {Sass}[http://sass-lang.com/] pre-processor (sass or scss).
+* Run them through ERB then Sass, what the heck. (Actually, this can be useful, like to allow
+  your app to set some Sass variables.)
+* Eliminate the need for deploy-time rake tasks that combine and minify your assets.
+* Combine, minify, and pre-process in memory instead of on disk, to accommodate read-only
+  filesystems (e.g. Heroku).
+* Cache the result using Rails action caching, and set the headers for far-future expiration,
+  allowing browsers and front-end caches like Varnish to hold assets for a long time.
+* Allow assets to be grouped, much like
+  {Scott Becker's venerable asset_packager}[http://synthesis.sbecker.net/pages/asset_packager].
+  (Example: You may want a set of stylesheets for your main interface, and another set for your admin
+  interface, maybe with some overlap. With DynamicAssets, your normal users won't pay the
+  penalty of downloading your admin styles.)
+* Allow CSS assets to refer to static images through relative URLs. That is, it doesn't break CSS urls.
+* Honor Rails' scheme for asset hosts.
+* Honor Rails' scheme for cache-busting.
+
+It seems that Rails 3.1 will offer many of these features off-the-shelf, which is
+cool. DynamicAssets allows you to get some of those features today in 3.0, but it
+wasn't intended as a back port or a stopgap. It just happens that serving assets
+dynamically is useful enough that multiple people have thought of implementing it.
+(See also: {Shoebox}[https://github.com/ddollar/shoebox])
+
+== How To
+
+1. Add this to your Gemfile:
+
+    gem "dynamic_assets"
+
+2. Put your CSS files in <tt>app/views/stylesheets</tt> and your JS files in
+   <tt>app/views/javascripts</tt>. Each filename's extension triggers an
+   optional pre-processor:
+
+    .css          = raw
+    .js           = raw
+    .css.erb      = process with ERB
+    .js.erb       = process with ERB
+    .css.sass     = process with Sass and assume sass syntax
+    .css.scss     = process with Sass and assume scss syntax
+    .css.sass.erb = process with ERB then Sass (sass)
+    .css.scss.erb = process with ERB then Sass (scss)
+
+   (Note that each file can be processed differently. You could stick one toe
+   into the Sass world by renaming one of your .css files to .scss.)
+
+3. Create a config/assets.yml file that looks something like this:
+
+    ---
+
+    config:
+      production, staging, test:
+        combine_asset_groups: true
+        minify: true
+        cache: true
+      development:
+        combine_asset_groups: true
+        minify: false
+        cache: false
+
+    javascripts:
+    - base:
+      - foo
+      - bar
+      - baz
+      - third-party/widget
+    - admin
+      - foo
+      - qux
+      - quux
+
+    stylesheets:
+    - app:
+      - reset
+      - application
+    - admin
+      - reset
+      - application
+      - admin
+
+   The assets.yml file sets some config values and then lists your assets. Don't be shy
+   about listing your assets; it's a good way to get noticed. This sample config
+   file says that in production, foo.js, bar.js, baz.js, and widget.js (which is
+   in app/views/javascripts/third-party) should be combined into one file,
+   minified, and served by your app as /assets/javascripts/base.js in such a way
+   that it'd be cached. In development, those files would be combined but not minified
+   or cached.
+
+4. In your layout, replace your usual CSS and JS references with
+
+    <%= stylesheet_asset_tag :app %>
+
+   wherever you want your stylesheet tags to appear and
+
+    <%= javascript_asset_tag :base %>
+
+   wherever you want your script tags to appear. The symbol argument to each
+   helper is the name of the group you defined in assets.yml. The helper will
+   produce one tag if the assets are combined, or multiple tags if they're not,
+   like the cowboy in <i>Mulholland Dr.</i>
+
+
+== Variables for ERB
+
+By default, assets are served by a small controller whose routes are added to
+your app automatically when the gem is loaded, but you can easily create your
+own controller if you prefer. One reason to do this would be to inject variables
+into an asset via ERB, like this:
+
+    class AssetsController < ApplicationController
+        include DynamicAssets::Controller
+
+        def show_stylesheet
+          @background_color = '#FFE'
+          render_asset :stylesheets, params[:name], "text/css"
+        end
+    end
+
+Now in app/views/stylesheets/application.css.erb you could do this:
+
+    body {
+        background-color: <%= @background_color %>;
+    }
+
+
+== Static Images Embedded in CSS
+
+Sometimes you'll install a JavaScript plugin that was created by someone
+else, and it will come with a stylesheet and images. The stylesheet may
+reference an image like this:
+
+    div.thing {
+        background: url(fancy_background.png);
+    }
+
+Browsers will find the image by looking in the same URL path as the
+stylesheet, so in a typical Rails environment, you might add these two
+files to your app as public/stylesheets/thing.css and
+public/stylesheets/fancy_background.png.
+
+With DynamicAssets, you'll put them here instead:
+
+    app/views/stylesheets/thing.css
+    public/stylesheets/thing/fancy_background.png
+
+and the processor will make sure the embedded URL is turned into a fully
+qualified one that will allow the browser to find
+/stylesheets/thing/fancy_background.png.
+
+== CSS Media Types
+
+If you have different CSS files for printing than for the screen, create
+separate groups in your assets.yml. Then include both groups in your layout:
+
+    <%= stylesheet_asset_tag :app %>
+    <%= stylesheet_asset_tag :app_printing, :media => "print" %>
+
+== Performance
+
+In production, assets can typically be cached aggressively. Like Rails,
+dynamic_assets adds a URL parameter to the asset path that will change
+if any of the underlying assets is modified, forcing clients to reload
+the asset. In production, I find dynamic assets to be quite speedy.
+
+But dynamic assets can sometimes be annoying during development. The
+sweet spot for my dev environment is to combine assets but not to
+minify or cache them (see assets.yml above). Here's why:
+
+=== Usually set assets not to be minified in development
+
+I usually leave minification off in development, because it does add some
+overhead to each asset request, and it makes them difficult to read if you
+need to debug them (like with Firebug). In production, caching minimizes
+the overhead, but you typically won't cache your assets in development,
+unless you're some sort of nut.
+
+=== Set assets to be combined, even in development and especially in test
+
+By default Rails reloads all classes with each new request in development
+mode. If you're not combining all of your assets, a single page load
+will result in an additional request to your app for each asset, which
+may result in a dozen requests to your dev server for one page, and each
+one will reload all of your classes. Combining assets in dev reduces the
+number of requests, shrinking your page load time. And unlike minification,
+using combined assets in dev is usually not a problem because the concatenated
+files are still quite readable. The one exception is that it makes it more
+difficult to find out which asset file includes the problem you're hunting
+down.
+
+<em>Note that one advantage of using DynamicAssets</em> instead of a
+deploy-time task is that you can get more exposure to your processed JavaScript.
+Concatenation and minification can sometimes uncover bugs in your scripts.
+(Example: a forgotten semicolon may be forgiven by a browser if it's at the
+end of a script file but it may cause problems if it's immediately followed by
+more code, tacked on from another file.)
+
+Call me silly, but I prefer to find out about that kind of error before I
+deploy my app, and with DynamicAssets I can easily set my test environment to
+combine and minify, so any full-stack testing will expose the problem.
+
+=== Or, to eliminate the biggest bottleneck, turn off class caching in development
+
+If you don't mind to restart your server every time you change a
+bit of Ruby code, you could edit your config/environments/development.rb
+to do this
+
+      config.cache_classes = true
+
+which would eliminate the biggest chunk of overhead in dev, class-reloading
+on every request.
+
+
+== Copyright
+
+Copyright (c) 2011 Robert Davis. See MIT-LICENSE for further details.
+

data/app/controllers/assets_controller.rb

@@ -0,0 +1,4 @@
+
+class AssetsController < ActionController::Base
+  include DynamicAssets::Controller
+end

data/app/helpers/dynamic_assets_helpers.rb

@@ -0,0 +1,63 @@
+
+module DynamicAssetsHelpers
+
+    def stylesheet_asset_tag(group_key, http_attributes = {})
+      DynamicAssets::Manager.asset_references_for_group_key(:stylesheets, group_key).map do |asset_ref|
+        path = stylesheet_asset_path asset_ref.name
+        path << "?#{asset_ref.mtime.to_i.to_s}" if asset_ref.mtime.present?
+
+        tag :link, {
+          :type   => "text/css",
+          :rel    => "stylesheet",
+          :media  => "screen",
+          :href   => asset_url_for_path(path)
+        }.merge!(http_attributes)
+
+      end.join.html_safe
+    end
+
+    def javascript_asset_tag(group_key, http_attributes = {})
+      DynamicAssets::Manager.asset_references_for_group_key(:javascripts, group_key).map do |asset_ref|
+        path = javascript_asset_path asset_ref.name
+        path << "?#{asset_ref.mtime.to_i.to_s}" if asset_ref.mtime.present?
+
+        content_tag :script, "", {
+          :type => "text/javascript",
+          :src  => asset_url_for_path(path)
+        }.merge!(http_attributes)
+
+      end.join.html_safe
+    end
+
+
+  protected
+
+    def asset_url_for_path(path)
+      raise "expected a path, not a full URL: #{path}" unless path.relative_url?
+      path = "/" + path unless path[0,1] == "/"
+      host = compute_asset_host path
+
+      if host
+        "#{host}#{path}"
+      else
+        path
+      end
+    end
+
+    # Extracted from Rails' AssetTagHelper, where it's private
+    def compute_asset_host(source)
+      if host = config.asset_host
+        if host.is_a?(Proc) || host.respond_to?(:call)
+          case host.is_a?(Proc) ? host.arity : host.method(:call).arity
+          when 2
+            request = controller.respond_to?(:request) && controller.request
+            host.call(source, request)
+          else
+            host.call(source)
+          end
+        else
+          (host =~ /%d/) ? host % (source.hash % 4) : host
+        end
+      end
+    end
+end

data/config/routes.rb

@@ -0,0 +1,12 @@
+
+Rails.application.routes.draw do
+
+  match '/assets/javascripts/:name.js' => 'assets#show_javascript', :as => :javascript_asset,
+    :format => "js",                        # Important for action-caching non-HTML resources
+    :constraints => { :name => /[^ ]+/ }    # By default, segments can't have dots. We allow all but space.
+
+  match '/assets/stylesheets/:name.css' => 'assets#show_stylesheet', :as => :stylesheet_asset,
+    :format => "css",                       # Important for action-caching non-HTML resources
+    :constraints => { :name => /[^ ]+/ }    # By default, segments can't have dots. We allow all but space.
+
+end

data/lib/dynamic_assets/config.rb

@@ -0,0 +1,109 @@
+require 'yaml'
+
+module DynamicAssets
+  module Config
+
+    CONFIG_VARS = %w(combine_asset_groups minify cache)
+
+    def init(yml_path)
+      @yml_path = yml_path
+      assets_hash.present?
+    end
+
+
+    #
+    #  Configuration
+    #
+
+    def combine_asset_groups?
+      @combine_asset_groups.nil? ? true : @combine_asset_groups
+    end
+
+    def minify?
+      @minify.nil? ? true : @minify
+    end
+
+    def cache?
+      @cache.nil? ? true : @cache
+    end
+
+
+    #
+    #  Methods
+    #
+
+    def asset_references_for_group_key(type, group_key)
+      assets_hash[type].if_present { |gs| gs[:by_group][group_key] }
+    end
+
+    def asset_reference_for_name(type, name)
+      assets_hash[type].if_present { |gs| gs[:by_name][name] }
+    end
+
+
+  protected
+
+    def yml
+      return @yml if @yml
+
+      if File.exists? @yml_path
+        @yml = YAML.load_file @yml_path
+        @yml.delete("config").if_present { |c| configure c }
+      else
+        @yml = {}
+      end
+
+      @yml
+    end
+
+    def configure(values)
+      values.each do |env_string, config_values|
+        next unless env_string.split(/ *, */).include? Rails.env
+
+        config_values.each do |name, value|
+          raise "unknown config variable: #{name}" unless CONFIG_VARS.include? name
+          instance_variable_set "@#{name}", value
+        end
+      end
+    end
+
+    def assets_hash
+      return @assets if @assets
+
+      assets = {}
+      yml.each do |key, values|
+        next if key == "config" || key.blank?
+
+        type = key.to_sym
+        groups = values
+
+        typed_assets = assets[type] = {
+          :by_name => {},
+          :by_group => {}
+        }
+
+        groups.map do |group_hash|
+          group_key = group_hash.keys.first
+          group_names = group_hash.values.first
+
+          assets_in_group = if combine_asset_groups?
+            # Create a single AssetReference for the group
+            name = group_key
+            a = typed_assets[:by_name][name] ||=
+              Reference.new_for_type(type, :name => name, :member_names => group_names)
+            [a]
+          else
+            # Create an AssetReference for each member of the group
+            group_names.map do |name|
+              typed_assets[:by_name][name] ||= Reference.new_for_type type, :name => name
+            end
+          end
+
+          typed_assets[:by_group][group_key.to_sym] = assets_in_group
+        end
+      end
+
+      @assets = assets
+    end
+  end
+end

data/lib/dynamic_assets/controller.rb

@@ -0,0 +1,40 @@
+
+module DynamicAssets
+  module Controller
+
+    def self.included(base)
+      base.caches_action :show_stylesheet, :show_javascript, :expires_in => 60.minutes,
+        :if => Proc.new { Manager.cache? }
+    end
+
+
+    #
+    #  Actions
+    #
+
+    def show_stylesheet
+      render_asset :stylesheets, params[:name], "text/css"
+    end
+
+    def show_javascript
+      render_asset :javascripts, params[:name], "text/javascript"
+    end
+
+
+  protected
+
+    def render_asset(type, name, mime_type)
+      asset = Manager.asset_reference_for_name type, name
+      raise ActionController::RoutingError.new "No route matches \"#{request.path}\"" unless asset
+
+      if Manager.cache?
+        response.cache_control[:public] = true
+        response.cache_control[:max_age] = 365.days
+        headers["Expires"] = (Time.now + 365.days).utc.httpdate
+      end
+
+      render :layout => false, :text => asset.content(binding), :content_type => mime_type
+    end
+  end
+
+end

data/lib/dynamic_assets/core_extensions.rb

@@ -0,0 +1,29 @@
+
+class String
+
+  # Returns true iff the receiver seems to be a relative, not a full, URL.
+  # By "relative url" we mean a URL with no host info, although it may
+  # begin with a slash.
+  def relative_url?
+    regexp = /^[^:\/]*:\/\/[^\/]*/
+    self[regexp].nil?
+  end
+
+end
+
+class Object
+
+  def if_present(*value)
+    raise ArgumentError, "Specify either a value or a block but not both" if value.empty? != block_given?
+    raise ArgumentError, "Too many arguments. Expected one." if value.length > 1
+
+    if !self.present?
+      self
+    elsif block_given?
+      yield self
+    else
+      value.first
+    end
+  end
+
+end

data/lib/dynamic_assets/engine.rb

@@ -0,0 +1,11 @@
+
+module DynamicAssets
+  class Engine < Rails::Engine
+
+      initializer 'dynamic_assets.config' do |app|
+        Manager.init "#{app.root}/config/assets.yml"
+        ActionView::Base.send :include, DynamicAssetsHelpers
+      end
+
+  end
+end

data/lib/dynamic_assets/manager.rb

@@ -0,0 +1,10 @@
+require 'yaml'
+
+module DynamicAssets
+
+  module Manager
+    extend Config
+    extend self   # act like a singleton class
+  end
+
+end

data/lib/dynamic_assets/reference/javascript_reference.rb

@@ -0,0 +1,19 @@
+module DynamicAssets
+
+  class JavascriptReference < Reference
+
+    def formats
+      %w(js)
+    end
+
+    def type
+      :javascripts
+    end
+
+    def minify(content_string)
+      JSMin.minify content_string
+    end
+
+  end
+
+end

data/lib/dynamic_assets/reference/stylesheet_reference.rb

@@ -0,0 +1,84 @@
+
+module DynamicAssets
+
+  class StylesheetReference < Reference
+
+    # CSS style sheets can contain relative urls like this:
+    #
+    #    background: url(something.png)
+    #
+    # The browser will look for the resource in the same location as
+    # the CSS file. However, we serve static resources like images
+    # from a different location, so the StylesheetReference will prepend
+    # RELATIVE_URL_ROOT to each such relative url in a stylesheet.
+
+    RELATIVE_URL_ROOT  = "/stylesheets"
+
+
+    def formats
+      %w(sass scss css)
+    end
+
+    def type
+      :stylesheets
+    end
+
+    def minify(content_string)
+      # From asset_packager. PENDING: replace with github.com/rgrove/cssmin ?
+      content_string.gsub(/\s+/, " ").# collapse space
+        gsub(/\/\*(.*?)\*\//, "").    # remove comments
+        gsub(/\} /, "}\n").           # add line breaks
+        gsub(/\n$/, "").              # remove last break
+        gsub(/ \{ /, " {").           # trim inside brackets
+        gsub(/; \}/, "}")             # trim inside brackets
+    end
+
+
+  protected
+
+    # Overridden to transform URLs embedded in the CSS
+    def read_member(member_name)
+      content_string = super
+      format = format_for_member_name member_name
+
+      content_string = case format
+      when :css
+        content_string
+      when :sass,:scss
+        location = File.dirname path_for_member_name(member_name)
+        Sass::Engine.new(content_string, :syntax => format, :load_paths => [location],
+          :cache => false).render
+      else raise "unknown format #{format}"
+      end
+
+      # PENDING: we could do something similar to insert the asset host,
+      # although we'd need to pass some context (namely the request) down
+      # from the controller to compute the asset host in the same way Rails
+      # does.
+      transform_urls member_name, content_string
+    end
+
+
+    def transform_urls(member_name, content_string)
+
+      # Prepend url_root to each relative url that doesn't start with a slash.
+      #
+      # Inside fancy.css, any of these:
+      #   url(one/thing.png)
+      #   url('one/thing.png')
+      #   url( "one/thing.png" )
+      #   url(../one/thing.png)
+      # will become
+      #   url(/stylesheets/fancy/one/thing.png)
+      #
+
+      content_string.gsub( /url\( *['"]?([^)]*[^'"])['"]? *\)/ ) do |s|
+        url = $1
+        url.gsub! /^(\.\.|\.)\//, ''
+        (url !~ /^\// && url.relative_url?) ? "url(#{RELATIVE_URL_ROOT}/#{member_name}/#{url})" : s
+      end
+    end
+
+  end
+
+end