merb-assets 1.1.0.rc1 → 1.1.0

data/lib/merb-assets.rb

@@ -12,6 +12,7 @@ Merb::Plugins.config[:asset_helpers] = {
     :asset_domain => "assets%s",
     :domain => "my-awesome-domain.com",
     :use_ssl => false,
+    :asset_timestamp => false,
     
     # Global prefix/suffix for css/js include tags, overridable in js_include_tag and css_include_tag
     #

data/lib/merb-assets/assets_mixin.rb

@@ -1,66 +1,72 @@
 module Merb
   # The AssetsMixin module provides a number of helper methods to views for
   # linking to assets and other pages, dealing with JavaScript and CSS.
+  #
+  # Merb provides views with convenience methods for links images and other
+  # assets.
   module AssetsMixin
     include Merb::Assets::AssetHelpers
-    # :section: Accessing Assets
-    # Merb provides views with convenience methods for links images and other
-    # assets.
 
+    ABSOLUTE_PATH_REGEXP = %r{^#{Merb::Const::HTTP}s?://}
 
     # This tests whether a random query string shall be appended to a url.
+    #
     # Basically, you tell it your intention and if it's ok to use default
     # config values, and it will either use your intention or the value
     # set in Merb::Config[:reload_templates]
     #
-    # ==== Parameters
-    # intention<Boolean>: true if a random string shall be appended
-    # allow_default<Boolean>: true if it's ok to use Merb::Config[:reload_templates]
-    #
-    # ==== Returns
-    # <Boolean> true if a random query string shall be appended
-    #
-    # ==== Examples
+    # @example
     #   Merb::AssetsMixin.append_random_query_string?(options[:reload])
     #   Merb::AssetsMixin.append_random_query_string?(options[:reload], !absolute)
+    #
+    # @param [Boolean] intention: true if a random string shall be appended
+    # @param [Boolean] allow_default: true if it's ok to use Merb::Config[:reload_templates]
+    # @return [Boolean] true if a random query string shall be appended
     def self.append_random_query_string?(intention, allow_default = true)
       intention.nil? && allow_default ? Merb::Config[:reload_templates] : intention
     end
 
-    # ==== Parameters
-    # none
+    # This tests whether a timestamp query string shall be appended to a url.
     #
-    # ==== Returns
-    # html<String>
+    # @see self.append_random_query_string?
     #
-    # ==== Examples
-    #  We want all possible matches in the FileSys up to the action name
-    #     Given:  controller_name = "namespace/controller"
-    #             action_name     = "action"
-    #  If all files are present should generate link/script tags for:
-    #     namespace.(css|js)
-    #     namespace/controller.(css|js)
-    #     namespace/controller/action.(css|js)
+    # @example
+    #   Merb::AssetsMixin.append_timestamp_query_string?(options[:timestamp])
+    #   Merb::AssetsMixin.append_timestamp_query_string?(options[:timestamp], !absolute)
     #
-    def auto_link
-      [auto_link_css, auto_link_js].join("\n")
+    # @param [Boolean] intention: true if a timestamp string shall be appended
+    # @param [Boolean] allow_default: true if it's ok to use Merb::Plugins.config[:asset_helpers][:asset_timestamp]
+    # @return [Boolean] true if a timestamp query string shall be appended
+    def self.append_timestamp_query_string?(intention, allow_default = true)
+      intention.nil? && allow_default ? Merb::Plugins.config[:asset_helpers][:asset_timestamp] : intention
     end
 
-    # ==== Parameters
-    # none
+    # Automatically generates link for CSS and JS
     #
-    # ==== Returns
-    # html<String>
+    # We want all possible matches in the FileSys up to the action name
+    #    Given:  controller_name = "namespace/controller"
+    #            action_name     = "action"
+    # @example
+    # If all files are present should generate link/script tags for:
+    #    namespace.(css|js)
+    #    namespace/controller.(css|js)
+    #    namespace/controller/action.(css|js)
     #
-    # ==== Examples
+    # @return [String] html
+    def auto_link
+      [auto_link_css, auto_link_js].join(Merb::Const::NEWLINE)
+    end
+
     # We want all possible matches in the file system upto the action name
     # for CSS. The reason for separating auto_link for CSS and JS is
     # performance concerns with page loading. See Yahoo performance rules
     # (http://developer.yahoo.com/performance/rules.html)
+    #
+    # @return [String] html
     def auto_link_css
       auto_link_paths.map do |path|
         asset_exists?(:stylesheet, path) ? css_include_tag(path) : nil
-      end.compact.join("\n")
+      end.compact.join(Merb::Const::NEWLINE)
     end
 
     # ==== Parameters
@@ -77,7 +83,7 @@ module Merb
     def auto_link_js
       auto_link_paths.map do |path|
         asset_exists?(:javascript, path) ? js_include_tag(path) : nil
-      end.compact.join("\n")
+      end.compact.join(Merb::Const::NEWLINE)
     end
 
     # ==== Parameters
@@ -103,10 +109,10 @@ module Merb
     # This is an auxiliary method which returns an array of all possible asset
     # paths for the current controller/action.
     def auto_link_paths
-      paths = (controller_name / action_name).split('/')
+      paths = (controller_name / action_name).split(Merb::Const::SLASH)
       first = paths.shift
       paths.inject( [first] ) do |memo, val|
-        memo.push [memo.last, val].join('/')
+        memo.push [memo.last, val].join(Merb::Const::SLASH)
       end
     end
 
@@ -130,22 +136,25 @@ module Merb
       %{<a #{ opts.to_xml_attributes }>#{name}</a>}
     end
 
-    # ==== Parameters
-    # img<~to_s>:: The image path.
-    # opts<Hash>:: Additional options for the image tag (see below).
+    # Generate IMG tag
     #
-    # ==== Options (opts)
-    # :path<String>::
+    # @param [String, #to_s] img The image path.
+    # @param [Hash] opts Additional options for the image tag (see below).
+    # @option opts [String] :path
     #   Sets the path prefix for the image. Defaults to "/images/" or whatever
     #   is specified in Merb::Config. This is ignored if img is an absolute
     #   path or full URL.
-    # :reload<Boolean>::
+    # @option opts [Boolean] :reload
     #   Override the Merb::Config[:reload_templates] value. If true, a random query param will be appended
     #   to the image url
+    # @option opts [Boolean, String] :timestamp
+    #   Override the Merb::Plugins.config[:asset_helpers][:asset_timestamp] value. If true, a timestamp query param will be appended
+    #   to the image url. The value will be File.mtime(Merb.dir_for(:public) / path).
+    #   If String is passed than it will be used as the timestamp.
     #
     # All other options set HTML attributes on the tag.
     #
-    # ==== Examples
+    # @example
     #   image_tag('foo.gif')
     #   # => <img src='/images/foo.gif' />
     #
@@ -162,13 +171,15 @@ module Merb
     #   or
     #   image_tag('/dynamic/charts')
     #   # => <img src="/dynamic/charts">
+    #
+    # @return [String]
     def image_tag(img, opts={})
       return "" if img.blank?
-      if img[0].chr == '/'
+      if img[0].chr == Merb::Const::SLASH
         opts[:src] = "#{Merb::Config[:path_prefix]}#{img}"
       else
         opts[:path] ||=
-          if img =~ %r{^https?://}
+          if img =~ ABSOLUTE_PATH_REGEXP
             absolute = true
             ''
           else
@@ -177,10 +188,11 @@ module Merb
         opts[:src] ||= opts.delete(:path) + img
       end
 
-      if AssetsMixin.append_random_query_string?(opts.delete(:reload), !absolute)
-        opts[:src] += opts[:src].include?('?') ? "&#{random_query_string}" : "?#{random_query_string}"
-      end
-
+      opts[:src] = append_query_string(opts[:src],
+                                       opts.delete(:reload),
+                                       opts.delete(:timestamp),
+                                       !absolute) 
+      
       %{<img #{ opts.to_xml_attributes } />}
     end
 
@@ -464,8 +476,9 @@ module Merb
       required_css(options).map { |req_js| css_include_tag(*req_js) }.join
     end
 
-    # ==== Parameters
-    # *scripts::
+    # Generate JavaScript include tag(s).
+    #
+    # @param [Array] scripts
     #   The scripts to include. If the last element is a Hash, it will be used
     #   as options (see below). If ".js" is left out from the script names, it
     #   will be added to them.
@@ -482,11 +495,12 @@ module Merb
     # :reload<Boolean>::
     #   Override the Merb::Config[:reload_templates] value. If true, a random query param will be appended
     #   to the js url
+    # @option opts [Boolean, String] :timestamp
+    #   Override the Merb::Plugins.config[:asset_helpers][:asset_timestamp] value. If true, a timestamp query param will be appended
+    #   to the image url. The value will be File.mtime(Merb.dir_for(:public) / path).
+    #   If String is passed than it will be used as the timestamp.
     #
-    # ==== Returns
-    # String:: The JavaScript include tag(s).
-    #
-    # ==== Examples
+    # @example
     #   js_include_tag 'jquery'
     #   # => <script src="/javascripts/jquery.js" type="text/javascript" charset="utf-8"></script>
     #
@@ -511,6 +525,8 @@ module Merb
     #   js_include_tag :application, :validation, :suffix => ".#{MyApp.version}"
     #   # => <script src="/javascripts/application.1.0.3.js" type="text/javascript" charset="utf-8"></script>
     #   #    <script src="/javascripts/validation.1.0.3.js" type="text/javascript" charset="utf-8"></script>
+    #
+    # @return [String] The JavaScript include tag(s).
     def js_include_tag(*scripts)
       options = scripts.last.is_a?(Hash) ? scripts.pop : {}
       return nil if scripts.empty?
@@ -534,9 +550,9 @@ module Merb
           src.insert(-ext_length,js_suffix)
         end
 
-        if AssetsMixin.append_random_query_string?(options[:reload])
-          src += src.include?('?') ? "&#{random_query_string}" : "?#{random_query_string}"
-        end
+        src = append_query_string(src,
+                                  options.delete(:reload),
+                                  options.delete(:timestamp))
 
         attrs = {
           :src => src,
@@ -549,31 +565,33 @@ module Merb
       return tags
     end
 
-    # ==== Parameters
-    # *stylesheets::
+    # Generate CSS include tag(s).
+    #
+    # @param [Array<*String, Hash>] stylesheets
     #   The stylesheets to include. If the last element is a Hash, it will be
     #   used as options (see below). If ".css" is left out from the stylesheet
     #   names, it will be added to them.
     #
     # ==== Options
-    # :charset<~to_s>::
+    # @option opts <String, #to_s> charset
     #   Charset which will be used as value for charset attribute
-    # :bundle<~to_s>::
+    # @option opts <String, #to_s> bundle
     #   The name of the bundle the stylesheets should be combined into.
-    # :media<~to_s>::
+    # @option opts <String, #to_s> media
     #   The media attribute for the generated link element. Defaults to :all.
-    # :prefix<~to_s>::
+    # @option opts <String, #to_s> prefix
     #   prefix to add to include tag, overrides any set in Merb::Plugins.config[:asset_helpers][:css_prefix]
-    # :suffix<~to_s>::
+    # @option opts <String, #to_s> suffix
     #   suffix to add to include tag, overrides any set in Merb::Plugins.config[:asset_helpers][:css_suffix]
-    # :reload<Boolean>::
+    # @option opts <Boolean> reload
     #   Override the Merb::Config[:reload_templates] value. If true, a random query param will be appended
     #   to the css url
+    # @option opts [Boolean, String] :timestamp
+    #   Override the Merb::Plugins.config[:asset_helper][:asset_timestamp] value. If true, a timestamp query param will be appended
+    #   to the image url. The value will be File.mtime(Merb.dir_for(:public) / path).
+    #   If String is passed than it will be used as the timestamp.
     #
-    # ==== Returns
-    # String:: The CSS include tag(s).
-    #
-    # ==== Examples
+    # @example
     #   css_include_tag 'style'
     #   # => <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css" charset="utf-8" />
     #
@@ -599,6 +617,8 @@ module Merb
     #
     #  css_include_tag :style, :suffix => ".#{MyApp.version}"
     #  # => <link href="/stylesheets/style.1.0.0.css" media="print" rel="Stylesheet" type="text/css" />
+    #
+    # @return [String] The CSS include tag(s)
     def css_include_tag(*stylesheets)
       options = stylesheets.last.is_a?(Hash) ? stylesheets.pop : {}
       return nil if stylesheets.empty?
@@ -614,6 +634,8 @@ module Merb
 
       tags = ""
 
+      reload = options.delete(:reload)
+      timestamp = options.delete(:timestamp)
       for stylesheet in stylesheets
         href = css_prefix.to_s + asset_path(:stylesheet, stylesheet)
         
@@ -622,9 +644,7 @@ module Merb
           href.insert(-ext_length,css_suffix)
         end
         
-        if AssetsMixin.append_random_query_string?(options[:reload])
-          href += href.include?('?') ? "&#{random_query_string}" : "?#{random_query_string}"
-        end
+        href = append_query_string(href, reload, timestamp)
 
         attrs = {
           :href => href,
@@ -761,9 +781,37 @@ module Merb
         extracted
       end
     end
+
+    def append_query_string(path, random, timestamp, allow_default = true)
+      random = AssetsMixin.append_random_query_string?(random, allow_default)
+      timestamp = AssetsMixin.append_timestamp_query_string?(timestamp, allow_default) 
+
+      query_string = if random
+                       random_query_string
+                     elsif timestamp
+                       timestamp == true ? timestamp_for_asset(path) : timestamp
+                     end
+
+      if query_string
+        path + (path.include?('?') ? "&#{query_string}" : "?#{query_string}")
+      else
+        path
+      end
+    end
     
     def random_query_string
       Time.now.strftime("%m%d%H%M%S#{rand(99)}")
     end
+
+    def timestamp_for_asset(path)
+      if path !~ ABSOLUTE_PATH_REGEXP
+        begin
+          File.mtime(Merb.dir_for(:public) / path).to_i
+        rescue
+          Merb.logger.warn "#{self.class}: Unable to get mtime for #{path}"
+        end 
+      end
+    end
+
   end
 end

data/lib/merb-assets/version.rb

@@ -1,5 +1,5 @@
 module Merb
   module Assets
-    VERSION = '1.1.0.rc1'.freeze
+    VERSION = '1.1.0'.freeze
   end
 end

data/spec/merb-assets_spec.rb

@@ -1,5 +1,7 @@
 require 'spec_helper'
 
+Merb.push_path(:public, 'spec/fixtures/')
+
 include Merb::AssetsMixin
 
 describe "Accessing Assets" do
@@ -182,6 +184,33 @@ describe "With Merb::Config[:reload_templates] set," do
   end
 end
 
+describe "With Merb::Plugins.config[:asset_helpers][:asset_timestamp] set," do
+  before(:all) do
+    Merb::Plugins.config[:asset_helpers][:asset_timestamp] = true
+  end
+  after(:all) do
+    Merb::Plugins.config[:asset_helpers][:asset_timestamp] = false
+  end
+
+  it "should create image tag with absolute url" do
+    image_tag('http://example.com/foo.gif').should ==
+      "<img src=\"http://example.com/foo.gif\" />"
+  end
+
+  it "should not add timestamp to the image tag with absolute url if :timestamp option is set" do
+    image_tag('http://example.com/foo.gif', :timestamp => true).should =~
+      %r{<img src="http://example.com/foo.gif" />}
+  end
+
+  it "should create image tag with relative url" do
+    image_tag('merb.jpg').should =~ %r{<img src="/images/merb.jpg\?\d+" />}
+  end
+
+  it "should create image tag with relative url and timestamp which is provided" do
+    image_tag('merb.jpg', :timestamp => 123456789).should =~ %r{<img src="/images/merb.jpg\?123456789" />}
+  end
+end
+
 describe "JavaScript related functions" do
   it "should escape js having quotes" do
     escape_js("'Lorem ipsum!' -- Some guy").should ==
@@ -313,16 +342,72 @@ describe "External JavaScript and Stylesheets" do
     result.should match(%r{/stylesheets/layout.css})
   end
    
-  it "should create a js include tag with a random query string" do
-    Merb::Config[:reload_templates] = true
-    result = js_include_tag('jquery.js')
-    result.should match(%r{/javascripts/jquery.js\?\d+})
-    Merb::Config[:reload_templates] = false
+  describe "with Merb::Config[:reload_templates] set" do
+    it "should create a js include tag with a random query string" do
+      Merb::Config[:reload_templates] = true
+      result = js_include_tag('jquery.js')
+      result.should match(%r{/javascripts/jquery.js\?\d+})
+      Merb::Config[:reload_templates] = false
+    end
+
+    it "should create a css include tag with a random query string" do
+      Merb::Config[:reload_templates] = true
+      result = css_include_tag('style.css')
+      result.should match(%r{/stylesheets/style.css\?\d+})
+      Merb::Config[:reload_templates] = false
+    end
   end
 
-  it "should create a css include tag with a random query string" do
-    result = css_include_tag('style.css', :reload => true)
-    result.should match(%r{/stylesheets/style.css\?\d+})
+  describe "with Merb::Plugins.config[:asset_helpers][:asset_timestamp] set" do
+    it "should create a css include tag with a timestamp query string" do
+      Merb::Plugins.config[:asset_helpers][:asset_timestamp] = true
+      result = css_include_tag('style.css')
+      result.should match(%r{/stylesheets/style.css\?\d+})
+      Merb::Plugins.config[:asset_helpers][:asset_timestamp] = false
+    end
+
+    it "should create a js include tag with a timestamp query string" do
+      Merb::Plugins.config[:asset_helpers][:asset_timestamp] = true
+      result = js_include_tag('jquery.js')
+      result.should match(%r{/javascripts/jquery.js\?\d+})
+      Merb::Plugins.config[:asset_helpers][:asset_timestamp] = false
+    end
+  end
+
+  describe "with :reload => true" do
+    it "should create a js include tag with a random query string" do
+      result = js_include_tag('jquery.js', :reload => true)
+      result.should match(%r{/javascripts/jquery.js\?\d+})
+    end
+
+    it "should create a css include tag with a random query string" do
+      result = css_include_tag('style.css', :reload => true)
+      result.should match(%r{/stylesheets/style.css\?\d+})
+    end
+  end
+
+  describe "with :timestamp => true" do
+    it "should create a js include tag with a timestamp query string" do
+      result = js_include_tag('jquery.js', :timestamp => true)
+      result.should match(%r{/javascripts/jquery.js\?\d+})
+    end
+
+    it "should create a css include tag with a timestamp query string" do
+      result = css_include_tag('style.css', :timestamp => true)
+      result.should match(%r{/stylesheets/style.css\?\d+})
+    end
+  end
+
+  describe "with :timestamp => 123456789" do
+    it "should create a js include tag with a 123456789 timestamp query string" do
+      result = js_include_tag('jquery.js', :timestamp => 123456789)
+      result.should match(%r{/javascripts/jquery.js\?123456789})
+    end
+
+    it "should create a css include tag with a 123456789 timestamp query string" do
+      result = css_include_tag('style.css', :timestamp => 123456789)
+      result.should match(%r{/stylesheets/style.css\?123456789})
+    end
   end
   
   it "should create a css include tag with the specified media" do

data/spec/spec_helper.rb

@@ -1,4 +1,5 @@
 require "rubygems"
+require "json"
 
 # Use current merb-core sources if running from a typical dev checkout.
 lib = File.expand_path('../../../merb-core/lib', __FILE__)

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: merb-assets
 version: !ruby/object:Gem::Version 
-  prerelease: true
+  prerelease: false
   segments: 
   - 1
   - 1
   - 0
-  - rc1
-  version: 1.1.0.rc1
+  version: 1.1.0
 platform: ruby
 authors: 
 - Ezra Zygmuntowicz
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-14 00:00:00 +00:00
+date: 2010-03-22 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -29,8 +28,7 @@ dependencies:
         - 1
         - 1
         - 0
-        - rc1
-        version: 1.1.0.rc1
+        version: 1.1.0
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -66,6 +64,9 @@ files:
 - lib/merb-assets/assets.rb
 - lib/merb-assets/assets_mixin.rb
 - lib/merb-assets/version.rb
+- spec/fixtures/images/merb.jpg
+- spec/fixtures/javascripts/jquery.js
+- spec/fixtures/stylesheets/style.css
 - spec/merb-assets_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
@@ -87,13 +88,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
       segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: